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ABOUT THIS CHAPTER 


This chapter describes QuickDraw, the part of the Toolbox that allows Macintosh 
programmers to perform highly complex graphic operations very easily and very 
quickly. It describes the data types used by QuickDraw and gives details of the 
procedures and functions available in QuickDraw. 
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ABOUT QUICKDRAW 


QuickDraw allows you to draw many different things on the Macintosh screen; some 
of these are illustrated in Figure 1. 


Text Lines Rectangles 
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Figure 1—-Samples of QuickDraw’s Abilities 


Figure 1-Samples of QuickDraw's Abilities 


You can draw: 


text characters in a number of proportionally-spaced fonts, with 
variations that include boldfacing, italicizing, underlining, and 
outlining 

straight lines of any length, width, and pattern 

a variety of shapes, including rectangles, rounded-corner rectangles, 
circles and ovals, and polygons, all either outlined and hollow or 
filled in with a pattern 

arcs of ovals, or wedge-shaped sections filled in with a pattern 
any other arbitrary shape or collection of shapes 

a picture composed of any combination of the above, drawn with just 
a single procedure call 


QuickDraw also has some other abilities that you won't find in many other 
graphics packages. These abilities take care of most of the "housekeeping"—the 
trivial but time-consuming overhead that's necessary to keep things in order. 
They include: 


The ability to define many distinct "ports" on the screen. Each port 
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has its own complete drawing environment—its own coordinate system, 
drawing location, character set, location on the screen, and so on. 
You can easily switch from one drawing port to another. 

e Full and complete "clipping" to arbitrary areas, so that drawing will 
occur only where you want. It's like an electronic coloring book that 
won't let you color outside the lines. You don't have to worry about 
accidentally drawing over something else on the screen, or drawing off 
the screen and destroying memory. 

¢ Off-screen drawing. Anything you can draw on the screen, you can also 
draw into an off-screen buffer, so you can prepare an image for an 
output device without disturbing the screen, or you can prepare a 
picture and move it onto the screen very quickly. 


And QuickDraw lives up to its name: It's very fast. The speed and 
responsiveness of the Macintosh user interface are due primarily to the speed of 
QuickDraw. You can do good-quality animation, fast interactive graphics, and 
complex yet speedy text displays using the full features of QuickDraw. This 
means you don't have to bypass the general-purpose QuickDraw routines by writing 
a lot of special routines to improve speed. 


In addition to its routines and data types, QuickDraw provides global variables 
that you can use from your Pascal program. For example, there's a variable named 
thePort that points to the current drawing port. 


Assembly-language note: See the discussion of InitGraf in the "QuickDraw 
Routines" section for details on how to access the 
QuickDraw global variables from assembly language. 


In conjunction with the Font Manager, QuickDraw supports font families, 
fractional character widths, and the disabling of font scaling; these features 
are described in the Font Manager chapter section. 


The 128K ROM version of QuickDraw supports all eight transfer modes for text 
drawing, instead of just srcOr, srcBic, and scrxXor. 


The size of a picture is a long word with a range of over four gigabytes. To get 
the size of a picture, use GetHandleSize instead of looking at the picSize 
field, which for compatibility contains the low 16 bits of the real size. Old 
code will work fine for pictures up to 32767 bytes. To check whether you have 
run out of memory during picture creation, test EmptyRect(picFrame); it returns 
TRUE if you have. 


The following bugs have been fixed in the 128K ROM: 


e RectInRgn used to return TRUE occasionally when the rectangle intersected 
the region's enclosing rectangle but not the actual region. 

e SectRgn, DiffRgn, UnionRgn, XorRgn, and FrameRgn used to cause a stack 
overflow for regions with more than 25 rectangles in one scan Line. 

e PtToAngle didn't work correctly when the angle was 90 and the aspect 
ratio was a power of two. 

e In some cases where the CopyBits source bitmap overlapped its destination, 
the transfer would destroy the source bitmap before it was used. 

¢ If you tried to draw a long piece of shadowed text with a tall font, 
QuickDraw would cause a stack overflow if there wasn't enough stack 
space for the required off-screen buffer. Now it detects the potential 
stack overflow and recurses on the left and right halves of the text. 
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¢ DrawText did not work correctly in pictures if the character count 
was greater than 255. 


The original QuickDraw described in this chapter has been expanded in two 
Significant areas: color capabilities with Color QuickDraw, which gives each 
pixel color information, and direct RGB colors with 32-Bit QuickDraw, where 
every pixel can contain a full RGB record with up to eight bits per component. 
Refer to the Color QuickDraw chapter and the 32-Bit QuickDraw documentation for 
more details on both of these enhancements to QuickDraw. 
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THE MATHEMATICAL FOUNDATION OF QUICKDRAW 


To create graphics that are both precise and pretty requires not supercharged 
features but a firm mathematical foundation for the features you have. If the 
mathematics that underlie a graphics package are imprecise or fuzzy, the 
graphics will be, too. QuickDraw defines some clear mathematical constructs that 
are widely used in its procedures, functions, and data types: the coordinate 
plane, the point, the rectangle, and the region. 


The Coordinate Plane 

ALL information about location or movement is given to QuickDraw in terms of 
coordinates on a plane. The coordinate plane is a two-dimensional grid, as 
illustrated in Figure 2. 

Note the following features of the QuickDraw coordinate plane: 


e All grid coordinates are integers (in the range —32767 to 32767). 
¢ All grid lines are infinitely thin. 


“32767 batt be 32767 


Figure 2-The Coordinate Plane 


Figure 2—The Coordinate Plane 


These concepts are important. First, they mean that the QuickDraw plane is 
finite, not infinite (although it's very large). Second, they mean that all 
elements represented on the coordinate plane are mathematically pure. 
Mathematical calculations using integer arithmetic will produce intuitively 
correct results. If you keep in mind that grid lines are infinitely thin, 
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you'll never have "endpoint paranoia"—the confusion that results from not 
knowing whether that last dot is included in the line. 


Points 


There are 4,294,836,224 unique points on the coordinate plane. Each point is at 

the intersection of a horizontal grid line and a vertical grid line. As the grid 
lines are infinitely thin, so a point is infinitely small. Of course, there are 

many more points on this grid than there are dots on the Macintosh screen: When 
using QuickDraw you associate small parts of the grid with areas on the screen, 

so that you aren't bound into an arbitrary, limited coordinate system. 


The coordinate origin (0,0) is in the middle of the grid. Horizontal coordinates 
increase as you move from left to right, and vertical coordinates increase as 
you move from top to bottom. This is the way both a TV screen and a page of 
English text are scanned: from the top left to the bottom right. 


Figure 3 shows the relationship between points, grid lines, and pixels, the 
physical dots on the screen. (Pixels correspond to bits in memory, as described 
in the next section.) 


You can store the coordinates of a point into a Pascal variable of type Point, 
defined by QuickDraw as a record of two integers: 


TYPE VHSelect = (v,h); 
Point = RECORD CASE INTEGER OF 
0: (v: INTEGER: {vertical coordinate} 
h: INTEGER); {horizontal coordinate} 
1: (vh: ARRAY[VHSelect] OF INTEGER) 
END; 
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grid line 


Figure 3-—Points and Pirels 
Figure 3—Points and Pixels 


The variant part of this record lets you access the vertical and horizontal 
coordinates of a point either individually or as an array. For example, if the 
variable goodPt is declared to be of type Point, the following will all refer to 
the coordinates of the point: 


goodPt.v goodPt.h 
goodPt.vh[v] goodPt.vh[h] 
Rectangles 


Any two points can define the top left and bottom right corners of a rectangle. 
As these points are infinitely small, the borders of the rectangle are 
infinitely thin (see Figure 4). 
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Figure 4-A Rectangle 
Figure 4—A Rectangle 


Rectangles are used to define active areas on the screen, to assign coordinate 
systems to graphic entities, and to specify the locations and sizes for various 
drawing commands. QuickDraw also allows you to perform many mathematical 
calculations on rectangles—changing their sizes, shifting them around, and so 
on. 


Note: Remember that rectangles, like points, are mathematical concepts 
that have no direct representation on the screen. The association 
between these conceptual elements and their physical representations 
is made by the BitMap data type, described in the following section. 


The data type for rectangles is called Rect, and consists of four integers or 
two points: 


TYPE Rect = RECORD CASE INTEGER OF 
0: (top: INTEGER; 
left: INTEGER; 
bottom: INTEGER; 
right: INTEGER) ; 
1: (topLeft: Point; 
botRight: Point) 
END; 


Again, the record variant allows you to access a variable of type Rect either as 
four boundary coordinates or as two diagonally opposite corner points. Combined 
with the record variant for points, all of the following references to the 
rectangle named aRect are legal: 


aRect {type Rect} 
aRect.topLeft aRect.botRight {type Point} 
aRect.top aRect. left {type INTEGER} 
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aRect.topLeft.v aRect.topLeft.h {type INTEGER} 


aRect.topLeft.vh[v] aRect.topLeft.vh[h] {type INTEGER} 
aRect.bottom aRect. right {type INTEGER} 
aRect.botRight.v aRect.botRight.h {type INTEGER} 


aRect.botRight.vh[v] aRect.botRight.vh[h] {type INTEGER} 


Note: If the bottom coordinate of a rectangle is equal to or less than 
the top, or the right coordinate is equal to or less than the left, 
the rectangle is an empty rectangle (that is, one that contains no bits). 


Regions 


Unlike most graphics packages that can manipulate only simple geometric 
structures (usually rectilinear, at that), QuickDraw has the ability to gather 
an arbitrary set of spatially coherent points into a structure called a region, 
and perform complex yet rapid manipulations and calculations on such structures. 
Regions not only make your programs simpler and faster, but will let you perform 
operations that would otherwise be nearly impossible. 


You define a region by calling routines that draw lines and shapes (even other 
regions). The outline of a region should be one or more closed loops. A region 
can be concave or convex, can consist of one area or many disjoint areas, and 

can even have "holes" in the middle. In Figure 5, the region on the left has a 
hole in the middle, and the region on the right consists of two disjoint areas. 


Figure 5—Regions 


Figure 5—Regions 


The data structure for a region consists of two fixed-length fields followed by 
a variable-length field: 


TYPE Region = RECORD 
rgnSize: INTEGER; {size in bytes} 
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rgnBBox: Rect; {enclosing rectangle} 
{more data if not rectangular} 
END; 


The rgnSize field contains the size, in bytes, of the region variable. The 
maximum size of a region is 32K bytes. The rgnBBox field is a rectangle that 
completely encloses the region. 


The simplest region is a rectangle. In this case, the rgnBBox field defines the 
entire region, and there's no optional region data. For rectangular regions (or 
empty regions), the rgnSize field contains 10. 


The region definition data for nonrectangular regions is stored in a compact way 
that allows for highly efficient access by QuickDraw routines. 


All regions are accessed through handles: 


TYPE RgnPtr 
RgnHandle 


“Region; 
“RgnPtr; 


Many calculations can be performed on regions. A region can be "expanded" or 
"shrunk" and, given any two regions, QuickDraw can find their union, 
intersection, difference, and exclusive-OR; it can also determine whether a 
given point intersects a region, and so on. 
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GRAPHIC ENTITIES 


Points, rectangles, and regions are all mathematical models rather than actual 
graphic elements—they're data types that QuickDraw uses for drawing, but they 
don't actually appear on the screen. Some entities that do have a direct graphic 
interpretation are the bit image, bit map, pattern, and cursor. This section 
describes these graphic entities and relates them to the mathematical constructs 
described above. 


Bit Images 


A bit image is a collection of bits in memory that have a rectilinear 
representation. Take a collection of words in memory and lay them end to end so 
that bit 15 of the Lowest-numbered word is on the left and bit 0 of the highest- 
numbered word is on the far right. Then take this array of bits and divide it, 
on word boundaries, into a number of equal-size rows. Stack these rows 
vertically so that the first row is on the top and the last row is on the 
bottom. The result is a matrix like the one shown in Figure 6—rows and columns 
of bits, with each row containing the same number of bytes. The number of bytes 
in each row of the bit image is called the row width of that image. A bit image 
can be any length that's a multiple of the row width. 


first 
lite 


row wideh 
is 3 bytes 


Figure 6-A Bit Image 


Figure 6-A Bit Image 


The screen itself is one large visible bit image. On a Macintosh 128K or 512K, 
for example, the screen is a 342-by-512 bit image, with a row width of 64 bytes. 
These 21,888 bytes of memory are displayed as a matrix of 175,104 pixels on the 
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screen, each bit corresponding to one pixel. If a bit's value is 0, its pixel is 
white; if the bit's value is 1, the pixel is black. 


Warning: The numbers given here apply only to the Macintosh 128K and 512K 
systems. To allow for your application running on any version of 
the Macintosh, you should never use explicit numbers for screen 
dimensions. The QuickDraw global variable screenBits (a bit map, 
described below) gives you access to a rectangle whose dimensions 
are those of the main screen, whatever version of the Macintosh is 
being used. 


On a Macintosh 128K or 512K, each pixel on the screen is square, and there are 
72 pixels per inch in each direction. On an unmodified Macintosh XL, each pixel 
is one and a half times taller than it is wide, meaning a rectangle 30 pixels 
wide by 20 tall looks square; there are 90 pixels per inch horizontally, and 60 
per inch vertically. A Macintosh XL may be modified to have square pixels. You 
can get the the screen resolution by calling the Toolbox Utility procedure 
ScreenRes. 


Note: The values given for pixels per inch may not be exactly the measurement 
on the screen, but they're the values you should use when calculating 
the size of printed output. 


Note: Since each pixel on the screen represents one bit in a bit image, 
wherever this chapter says "bit", you can substitute "pixel" if the 
bit image is the screen. Likewise, this chapter often refers to pixels 
on the screen where the discussion applies equally to bits in an off- 
screen bit image. 


Bit Maps 


A bit map in QuickDraw is a data structure that defines a physical bit image in 
terms of the coordinate plane. A bit map has three parts: a pointer to a bit 
image, the row width of that image, and a boundary rectangle that gives the bit 
map both its dimensions and a coordinate system. 


There can be several bit maps pointing to the same bit image, each imposing a 
different coordinate system on it. This important feature is explained in 
"Coordinates in GrafPorts", below. 

As shown in Figure 7, the structure of a bit map is as follows: 


TYPE BitMap = RECORD 


baseAddr: Ptr; {pointer to bit image} 

rowBytes: INTEGER; {row width} 

bounds: Rect {boundary rectangle} 
END; 
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Figure 7-A Bit Map 


Figure 7-A Bit Map 


BaseAddr is a pointer to the beginning of the bit image in memory. RowBytes is 
the row width in bytes. Both of these must always be even: A bit map must 
always begin on a word boundary and contain an integral number of words in each 
row. 


The bounds field is the bit map's boundary rectangle, which both encloses the 
active area of the bit image and imposes a coordinate system on it. The top left 
corner of the boundary rectangle is aligned around the first bit in the bit 
image. 


The relationship between the boundary rectangle and the bit image in a bit map 
is simple yet very important. First, some general rules: 


¢ Bits in a bit image fall between points on the coordinate plane. 
e A rectangle that is H points wide and V points tall encloses 
exactly (H-1)*(V-1) bits. 


The coordinate system assigns integer values to the lines that border and 
separate bits, not to the bit positions themselves. For example, if a bit map is 
assigned the boundary rectangle with corners (10,-8) and (34,8), the bottom 
right bit in the image will be between horizontal coordinates 33 and 34, and 
between vertical coordinates 7 and 8 (see Figure 8). 
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Figure §-Coordinates and Bit Maps 


Figure 8—Coordinates and Bit Maps 


The width of the boundary rectangle determines how many bits of one row are 
logically owned by the bit map. This width must not exceed the number of bits in 
each row of the bit image. The height of the boundary rectangle determines how 
many rows of the image are logically owned by the bit map. The number of rows 
enclosed by the boundary rectangle must not exceed the number of rows in the bit 
image. 


Normally, the boundary rectangle completely encloses the bit image. If the 
rectangle is smaller than the dimensions of the image, the least significant 
bits in each row, as well as the last rows in the image, aren't affected by any 
operations on the bit map. 


There's a QuickDraw global variable, named screenBits, that contains a bit map 
corresponding to the screen of the Macintosh being used. Wherever your program 
needs the exact dimensions of the screen, it should get them from the boundary 
rectangle of this variable. 


Patterns 


A pattern is a 64-bit image, organized as an 8-by-8-bit square, that's used to 
define a repeating design (such as stripes) or tone (such as gray). Patterns can 
be used to draw lines and shapes or to fill areas on the screen. 


When a pattern is drawn, it's aligned so that adjacent areas of the same pattern 
in the same graphics port will blend with it into a continuous, coordinated 
pattern. QuickDraw provides predefined patterns in global variables named white, 
black, gray, ltGray, and dkGray. Any other 64-bit variable or constant can also 
be used as a pattern. The data type definition for a pattern is as follows: 


TYPE Pattern = PACKED ARRAY[0..7] OF 0..255; 


The row width of a pattern is one byte. 
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Cursors 


A cursor is a small image that appears on the screen and is controlled by the 
mouse. (It appears only on the screen, and never in an off-screen bit image. ) 


Note: Macintosh user manuals call this image a "pointer", since it points 
to a location on the screen. To avoid confusion with other meanings 
of "pointer" in Inside Macintosh, we use the alternate term "cursor". 


A cursor is defined as a 256-bit image, a 16-by-16-bit square. The row width of 
a cursor is two bytes. Figure 9 illustrates four cursors. 


Figure 9-Curso1rs 


Figure 9—Cursors 


A cursor has three fields: a 16-word data field that contains the image itself, 
a 16-word mask field that contains information about the screen appearance of 
each bit of the cursor, and a hotSpot point that aligns the cursor with the 
mouse location. 


TYPE Bitsl6 = ARRAY[0..15] OF INTEGER; 


Cursor = RECORD 


data: Bits16; {cursor image} 

mask: Bits16; {cursor mask} 

hotSpot: Point {point aligned with mouse} 
END; 


The data for the cursor must begin on a word boundary. 


The cursor appears on the screen as a 16-by-16-bit square. The appearance of 
each bit of the square is determined by the corresponding bits in the data and 
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mask and, if the mask bit is 0, by the pixel "under" the cursor (the pixel 
already on the screen in the same position as this bit of the cursor): 


Data Mask Resulting pixel on screen 

0 1 White 

1 1 Black 

0 0 Same as pixel under cursor 

1 0 Inverse of pixel under cursor 


Notice that if all mask bits are 0, the cursor is completely transparent, in 
that the image under the cursor can still be viewed: Pixels under the white 
part of the cursor appear unchanged, while under the black part of the cursor, 
black pixels show through as white. 


The hotSpot aligns a point (not a bit) in the image with the mouse location. 
Imagine the rectangle with corners (0,0) and (16,16) framing the image, as in 
each of the examples in Figure 9; the hotSpot is defined in this coordinate 
system. A hotSpot of (0,0) is at the top left of the image. For the arrow in 
Figure 9 to point to the mouse location, (1,1) would be its hotSpot. A hotSpot 
of (8,8) is in the exact center of the image; the center of the plus sign or 
circle in Figure 9 would coincide with the mouse location if (8,8) were the 
hotSpot for that cursor. Similarly, the hotSpot for the pointing hand would be 
(16,9). 


Whenever you move the mouse, the low-level interrupt-driven mouse routines move 
the cursor's hotSpot to be aligned with the new mouse location. 


QuickDraw supplies a predefined cursor in the global variable named arrow; this 
is the standard arrow cursor (illustrated in Figure 9). 


Graphic Entities as Resources 


You can create cursors and patterns in your program code, but it's usually 
Simpler and more convenient to store them in a resource file and read them in 
when you need them. Standard cursors and patterns are available not only through 
the global variables provided by QuickDraw, but also as system resources stored 
in the system resource file. QuickDraw itself operates independently of the 
Resource Manager, so it doesn't contain routines for accessing graphics-related 
resources; instead, these routines are included in the Toolbox Utilities (see 
the Toolbox Utilities chapter for more information). 


Besides patterns and cursors, two other graphic entities that may be stored in 
resource files (and accessed via Toolbox Utility routines) are a QuickDraw 
picture, described later in this chapter, and an icon, a 32-by-32 bit image 
that's used to graphically represent an object, concept, or message. 
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THE DRAWING ENVIRONMENT: GRAFPORT 


A grafPort is a complete drawing environment that defines where and how graphic 
operations will take place. You can have many grafPorts open at once, and each 
one will have its own coordinate system, drawing pattern, background pattern, 
pen size and location, character font and style, and bit map in which drawing 
takes place. You can instantly switch from one port to another. GrafPorts are 
the structures upon which a program builds windows, which are fundamental to the 
Macintosh “overlapping windows" user interface. Besides being used for windows 
on the screen, grafPorts are used for printing and for off-screen drawing. 


A grafPort is defined as follows: 


TYPE GrafPtr = %*GrafPort; 
GrafPort = RECORD 
device: INTEGER; {device-specific information} 
portBits: BitMap; {grafPort's bit map} 
portRect: Rect; {grafPort's rectangle} 
visRgn: RgnHandle; {visible region} 
clipRgn: RgnHandle; {clipping region} 
bkPat: Pattern; {background pattern} 
fillPat: Pattern; {fill pattern} 
pnLoc: Point; {pen location} 
pnSize: Point; {pen size} 
pnMode: INTEGER; {pen's transfer mode} 
pnPat: Pattern; {pen pattern} 
pnVis: INTEGER; {pen visibility} 
txFont: INTEGER; {font number for text} 
txFace: Style; {text's character style} 
txMode: INTEGER; {text's transfer mode} 
txSize: INTEGER; {font size for text} 
spExtra: Fixed; {extra space} 
fgColor: LONGINT; {foreground color} 
bkColor: LONGINT; {background color} 
colrBit: INTEGER; {color bit} 
patStretch: INTEGER; {used internally} 
picSave: Handle; {picture being saved} 
rgnSave: Handle; {region being saved} 
polySave: Handle; {polygon being saved} 
grafProcs: QDProcsPtr {low-level drawing routines} 
END; 


Note that picSave is a Handle used internally by QuickDraw while it is saving a 
picture, and rgnSave and polySave are used by QuickDraw as flags; they are set 
to "1" when the corresponding action is taking place. 


ALL QuickDraw operations refer to grafPorts via grafPtrs. (For historical 
reasons, grafPort is one of the few objects in the Macintosh system software 
that's referred to by a pointer rather than a handle. ) 

Warning: You can access all fields and subfields of a grafPort normally, 
but you should not store new values directly into them. QuickDraw 
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has routines for altering all fields of a grafPort, and using 
these routines ensures that changing a grafPort produces no 
unusual side effects. 


The device field of a grafPort contains device-specific information that's used 
by the Font Manager to achieve the best possible results when drawing text in 
the grafPort. There may be physical differences in the same logical font for 
different output devices, to ensure the highest-quality printing on the device 
being used. The default value of the device field is 0, for best results on 
output to the screen. For more information, see the Font Manager chapter. 


The portBits field is the bit map that points to the bit image to be used by the 
grafPort. The default bit map uses the entire screen as its bit image. The bit 
map may be changed to indicate a different structure in memory: All graphics 
routines work in exactly the same way regardless of whether their effects are 
visible on the screen. A program can, for example, prepare an image to be 
printed on a printer without ever displaying the image on the screen, or develop 
a picture in an off-screen bit map before transferring it to the screen. The 
portBits.bounds rectangle determines the coordinate system of the grafPort; all 
other coordinates in the grafPort are expressed in this system. 


The portRect field is a rectangle that defines a subset of the bit map that will 
be used for drawing: All drawing done by the application occurs inside the 
portRect. Its coordinates are in the coordinate system defined by the 
portBits.bounds rectangle. The portRect usually falls within the portBits.bounds 
rectangle, but it's not required to do so. The portRect usually defines the 
"writable" interior area of a window, document, or other object on the screen. 


The visRgn field is manipulated by the Window Manager; you will normally never 
change a grafPort's visRgn. It indicates the region of the grafPort that's 
actually visible on the screen, that is, the part of the window that's not 
covered by other windows. For example, if you move one window in front of 
another, the Window Manager logically removes the area of overlap from the 
visRgn of the window in back. When you draw into the back window, whatever's 
being drawn is clipped to the visRgn so that it doesn't run over onto the front 
window. The default visRgn is set to the portRect. 


The clipRgn is the grafPort's clipping region, an arbitrary region that you can 
use to limit drawing to any region within the portRect. If, for example, you 
want to draw a half circle on the screen, you can set the clipRgn to half the 
square that would enclose the whole circle, and then draw the whole circle. Only 
the half within the clipRgn will actually be drawn in the grafPort. The default 
clipRgn is set arbitrarily large, you have full control over its setting; as a 
matter of recommended programming practice, it is advisable to make the default 
clipRgn rectangle smaller. 


Figure 10 illustrates a typical bit map (as defined by portBits), portRect, 
visRgn, and clipRgn. 
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grafForts 


grafPort "A" 


portBits bownds of portRect of grafPort "a" 


visRig@y of grafFort "A" clipFivm of grafFort "B" 


Figure 10-GrafPort Regions 
Figure 10-GrafPort Regions 


The bkPat and fillPat fields of a grafPort contain patterns 
QuickDraw routines. BkPat is the "background" pattern that's 
is erased or when bits are scrolled out of it. When asked to 
specified pattern, QuickDraw stores the given pattern in the 
then calls a low-level drawing routine that gets the pattern 
The various graphic operations are discussed in detail later 
of individual QuickDraw routines. 


Of the next ten fields, the first five determine characteris 
pen and the last five determine characteristics of any text 
these are described in separate sections below. 


The fgColor, bkColor, and colrBit fields contain values rela 
color. FgColor is the grafPort's foreground color and bkColo 
color. ColrBit tells the color imaging software which plane 
to draw into. For more information, see "Drawing in Color" i 
"General Discussion of Drawing". 


The patStretch field is used during output to a printer to e 
necessary. The application should not change its value. 


The picSave, rgnSave, and polySave fields reflect the state 
and polygon definition, respectively. The application should 
about exactly what information the handle, if any, leads to; 
save the current value of rgnSave, set the field to NIL to d 
definition, and later restore it to the saved value to resum 
definition. The picSave and polySave fields work similarly f 
polygons. 
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Finally, the grafProcs field may point to a special data structure that the 
application stores into if it wants to customize QuickDraw drawing routines or 
use QuickDraw in other advanced, highly specialized ways (see "Customizing 
QuickDraw Operations"). If grafProcs is NIL, QuickDraw responds in the standard 
ways described in this chapter. 


Pen Characteristics 


The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal with the 
graphics "pen". Each grafPort has one and only one such pen, which is used for 
drawing lines, shapes, and text. The pen has four characteristics: a location, 
a size (height and width), a drawing mode, and a drawing pattern (see Figure 
11). 


hs 
essa 


pattern 


Figure 11-A Graphics Pen 
Figure 11—-A Graphics Pen 


The pnLoc field specifies the point where QuickDraw will begin drawing the next 
line, shape, or character. It can be anywhere on the coordinate plane: There 
are no restrictions on the movement or placement of the pen. Remember that the 
pen location is a point in the grafPort's coordinate system, not a pixel ina 
bit image. The top left corner of the pen is at the pen location; the pen hangs 
below and to the right of this point. 


The pen is rectangular in shape, and its width and height are specified by 
pnSize. The default size is a 1-by-1-bit square; the width and height can range 
from (0,0) to (30000,30000). If either the pen width or the pen height is less 
than 1, the pen will not draw. 


The pnMode and pnPat fields of a grafPort determine how the bits under the pen 
are affected when lines or shapes are drawn. The pnPat is a pattern that's used 
like the "ink" in the pen. This pattern, like all other patterns drawn in the 
grafPort, is always aligned with the port's coordinate system: The top left 
corner of the pattern is aligned with the top left corner of the portRect, so 
that adjacent areas of the same pattern will blend into a continuous, 
coordinated pattern. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
QUICKDRAW ¢ 22 of 86 


The pnMode field determines how the pen pattern is to affect what's already in 
the bit image when lines or shapes are drawn. When the pen draws, QuickDraw 
first determines what bits in the bit image will be affected and finds their 
corresponding bits in the pattern. It then does a bit-by-bit comparison based on 
the pen mode, which specifies one of eight Boolean operations to perform. The 
resulting bit is stored into its proper place in the bit image. The pen modes 
are described under "Transfer Modes" in the section "General Discussion of 
Drawing". 


The pnVis field determines the pen's visibility, that is, whether it draws on 
the screen. For more information, see the descriptions of HidePen and ShowPen 
under "Pen and Line-Drawing Routines" in the "QuickDraw Routines" section. 


Text Characteristics 


The txFont, txFace, txMode, txSize, and spExtra fields of a grafPort determine 
how text will be drawn—-the font, style, and size of characters and how they will 
be placed in the bit image. QuickDraw can draw characters as quickly and easily 
as it draws lines and shapes, and in many prepared fonts. Font means the 
complete set of characters of one typeface. The characters may be drawn in any 
size and character style (that is, with stylistic variations such as bold, 
italic, and underline). Figure 12 shows two characters drawn by QuickDraw and 
some terms associated with drawing text. 


ascent line 
ascent 
arceeat hase line 
descent line 


character width 
Figure 12-QuickDraw Characters 


Figure 12—QuickDraw Characters 
Text is drawn with the base line positioned at the pen location. 


The txFont field is a font number that identifies the character font to be used 
in the grafPort. The font number 0 represents the system font. For more 
information about the system font, the other font numbers recognized by the Font 
Manager, and the construction, layout, and loading of fonts, see the Font 
Manager chapter. 


A character font is defined as a collection of images that make up the 
individual characters of the font. The characters can be of unequal widths, and 
they're not restricted to their "cells": The lower curl of a lowercase j, for 
example, can stretch back under the previous character (typographers call this 
kerning). A font can consist of up to 255 distinct characters, yet not all 
characters need to be defined in a single font. In addition, each font contains 
a missing symbol to be drawn in case of a request to draw a character that's 
missing from the font. 
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The txFace field controls the character style of the text with values from the 
set defined by the Style data type: 


TYPE StyleItem 
Style 


= (bold,italic,underline, outline, shadow, condense,extend) ; 

= SET OF StyleItem; 

Assembly-language note: In assembly language, this set is stored as a word 
whose low-order byte contains bits representing the 
style. The bit numbers are specified by the following 
global constants: 


boldBit . EQU 0 
italicBit . EQU 1 
ulineBit . EQU 2 
outlineBit . EQU 3 
shadowBit . EQU 5 
extendBit . EQU 6 


If all bits are 0, it represents the plain character 
style. 


You can apply stylistic variations either alone or in combination; Figure 13 
illustrates some as applied to the Geneva font. Most combinations usually look 
good only for large font sizes. 


Plain Characters 
Bold Characters 
JRE Ca 
Underlined Characters 


BoldgOutlinedge haracte rs) 


Figure 13-S5tylistic Yarnations 
Figure 13-Stylistic Variations 


If you specify bold, each character is repeatedly drawn one bit to the right an 
appropriate number of times for extra thickness. 


Italic adds an italic slant to the characters. Character bits above the base 
line are skewed right; bits below the base line are skewed left. 


Underline draws a line below the base line of the characters. If part of a 
character descends below the base line (as "y" in Figure 13), the underline 
isn't drawn through the pixel on either side of the descending part. 
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Outline makes a hollow, outlined character rather than a solid one. Shadow also 
makes an outlined character, but the outline is thickened below and to the right 
of the character to achieve the effect of a shadow. If you specify bold along 
with outline or shadow, the hollow part of the character is widened. 


Condense and extend affect the horizontal distance between all characters, 
including spaces. Condense decreases the distance between characters and extend 
increases it, by an amount that the Font Manager determines is appropriate. 


The txMode field controls the way characters are placed in the bit image. It 
functions much like a pnMode: When a character is drawn, QuickDraw determines 
which bits in the bit image will be affected, does a bit-by-bit comparison based 
on the mode, and stores the resulting bits into the bit image. These modes are 
described under "Transfer Modes" in the section "General Discussion of Drawing". 
Only three of them-srcOr, srcXor, and srcBic—should be used for drawing text. 


Note: If you use scrCopy, some extra blank space will be appended at the 
end of the text. 


The txSize field specifies the font size in points (where "point" is a 
typographical term meaning approximately 1/72 inch). Any size from 1 to 127 
points may be specified. If the Font Manager doesn't have the font in a 
specified size, it will scale a size it does have as necessary to produce the 
size desired. A value of 0 in this field represents the system font size (12 
points). 


Finally, the spExtra field is useful when a line of characters is to be drawn 
justified such that it's aligned with both a left and a right margin (sometimes 
called "full justification"). SpExtra contains a fixed-point number equal to the 
average number of pixels by which each space character should be widened to fill 
out the line. The Fixed data type is described in the Macintosh Memory 
Management: An Introduction chapter. 
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COORDINATES IN GRAFPORTS 


Each grafPort has its own local coordinate system. All fields in the grafPort 
are expressed in these coordinates, and all calculations and actions performed 
in QuickDraw use the local coordinate system of the currently selected port. 


Two things are important to remember: 


¢ Each grafPort maps a portion of the coordinate plane into a similarly- 
sized portion of a bit image. 
« The portBits.bounds rectangle defines the local coordinates for a grafPort. 


The top left corner of portBits.bounds is always aligned around the first bit in 
the bit image; the coordinates of that corner "anchor" a point on the grid to 
that bit in the bit image. This forms a common reference point for multiple 
grafPorts that use the same bit image (such as the screen); given a 
portBits.bounds rectangle for each port, you know that their top left corners 
coincide. 


The relationship between the portBits.bounds and portRect rectangles is very 
important: The portBits.bounds rectangle establishes a coordinate system for 
the port, and the portRect rectangle indicates the section of the coordinate 
plane (and thus the bit image) that will be used for drawing. The portRect 
usually falls inside the portBits.bounds rectangle, but it's not required to do 
so. 


When a new grafPort is created, its bit map is set to point to the entire 
screen, and both the portBits.bounds and the portRect are set to rectangles 
enclosing the screen. The point (0,0) corresponds to the screen's top left 
corner. 


You can redefine the local coordinates of the top left corner of the grafPort's 
portRect, using the SetOrigin procedure. This offsets the coordinates of the 
grafPort's portBits.bounds rectangle, recalculating the coordinates of all 
points in the grafPort to be relative to the new corner coordinates. For 
example, consider these procedure calls: 


SetPort(gamePort) ; 
SetOrigin(90,80) 


The call to SetPort sets the current grafPort to gamePort; the call to SetOrigin 
changes the local coordinates of the top left corner of that port's portRect to 
(90,80) (see Figure 14). 
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Figure 14-Changing Local Coordinates 


Figure 14—Changing Local Coordinates 
This offsets the coordinates of the following elements: 


gamePort’.portBits.bounds 
gamePort”.portRect 
gamePort”.visRgn 


These three elements are always kept "in sync". 


Notice that when the local coordinates of a grafPort are offset, the grafPort's 
clipRgn and pen location are not offset. A good way to think of it is that the 
port's structure "sticks" to the screen, while the document in the grafPort 
(along with the pen and clipRgn) "sticks" to the coordinate system. For example, 
in Figure 14, before SetOrigin, the visRgn and clipRgn are the same as the 
portRect. After the SetOrigin call, the locations of portBits.bounds, portRect, 
and visRgn do not change on the screen; their coordinates are simply offset. As 
always, the top left corner of portBits.bounds remains "anchored" around the 
first bit in the bit image (the first pixel on the screen); the image on the 
screen doesn't move as a result of SetOrigin. However, the pen location and 
clipRgn do move on the screen; the top left corner of the clipRgn is still 
(100,100), but this location has moved down and to the right, and the pen has 
similarly moved. 


If you're moving, comparing, or otherwise dealing with mathematical items in 
different grafPorts (for example, finding the intersection of two regions in two 
different grafPorts), you must adjust to a common coordinate system before you 
perform the operation. A QuickDraw procedure, LocalToGlobal, lets you convert a 
point's local coordinates to a global coordinate system where the top left 
corner of the bit image is (0,0); by converting the various local coordinates to 
global coordinates, you can compare and mix them with confidence. For more 
information, see the description of LocaltoGlobal under "Calculations with 
Points" in the "QuickDraw Routines" section. 
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GENERAL DISCUSSION OF DRAWING 


Drawing occurs: 


« always inside a grafPort, in the bit image and coordinate system 
defined by the grafPort's bit map 

* always within the intersection of the grafPort's portBits.bounds 
and portRect, and clipped to its visRgn and clipRgn 

¢ always at the grafPort's pen location 

* usually with the grafPort's pen size, pattern, and mode 


With QuickDraw routines, you can draw lines, shapes, and text. Shapes include 
rectangles, ovals, rounded-corner rectangles, wedge-shaped sections of ovals, 
regions, and polygons. 


Lines are defined by two points: the current pen location and a destination 
location. When drawing a line, QuickDraw moves the top left corner of the pen 
along the mathematical trajectory from the current location to the destination. 
The pen hangs below and to the right of the trajectory (see Figure 15). 


Figure 15-Drawing Lines 


Figure 15—-Drawing Lines 


Note: No mathematical element (such as the pen location) is ever affected 
by clipping; clipping only determines what appears where in the bit 
image. If you draw a line to a location outside the intersection of 
the portRect, visRgn and clipRgn, the pen location will move there, 
but only the portion of the line that's inside that area will actually 
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be drawn. This is true for all drawing routines. 


Rectangles, ovals, and rounded-corner rectangles are defined by two corner 
points. The shapes always appear inside the mathematical rectangle defined by 
the two points. A region is defined in a more complex manner, but also appears 
only within the rectangle enclosing it. Remember, these enclosing rectangles 
have infinitely thin borders and are not visible on the screen. 


As illustrated in Figure 16, shapes may be drawn either solid (filled in with a 
pattern) or framed (outlined and hollow). 


pen height 
+ 


ai 


pen 
RO witth 


Figure 16-0] Shapes and Framed Shapes 
Figure 16-Solid Shapes and Framed Shapes 


In the case of framed shapes, the outline appears completely within the 
enclosing rectangle—with one exception—and the vertical and horizontal thickness 
of the outline is determined by the pen size. The exception is polygons, as 
discussed in the section "Pictures and Polygons" below. 


The pen pattern is used to fill in the bits that are affected by the drawing 
Operation. The pen mode defines how those bits are to be affected by directing 
QuickDraw to apply one of eight Boolean operations to the bits in the shape and 
the corresponding pixels on the screen. 


Text drawing doesn't use the pnSize, pnPat, or pnMode, but it does use the 
pnLoc. QuickDraw starts drawing each character from the current pen location, 
with the character's base line at the pen location. After a character is drawn, 
the pen moves to the right to the location where it will draw the next 
character. No wraparound or carriage return is performed automatically. Clipping 
of text is performed in exactly the same manner as all other clipping in 
QuickDraw. 


Transfer Modes 


@ SpInside Macintosh * Version 1.0 * November 1989 * Apple Computer 
QUICKDRAW ¢ 29 of 86 


When lines or shapes are drawn, the pnMode field of the grafPort determines how 
the drawing is to appear in the port's bit image; similarly, the txMode field 
determines how text is to appear. There's also a QuickDraw procedure that 
transfers a bit image from one bit map to another, and this procedure has a mode 
parameter that determines the appearance of the result. In all these cases, the 
mode, called a transfer mode, specifies one of eight Boolean operations: For 
each bit in the item to be drawn, QuickDraw finds the corresponding bit in the 
destination bit map, performs the Boolean operation on the pair of bits, and 
stores the resulting bit into the bit image. 


There are two types of transfer mode: 


¢ pattern transfer modes, for drawing lines or shapes with a pattern 
* source transfer modes, for drawing text or transferring any bit 
image between two bit maps 


For each type of mode, there are four basic operations—Copy, Or, Xor, and Bic 
("bit clear"). The Copy operation simply replaces the pixels in the destination 
with the pixels in the pattern or source, "painting" over the destination 
without regard for what's already there. The Or, Xor, and Bic operations leave 
the destination pixels under the white part of the pattern or source unchanged, 
and differ in how they affect the pixels under the black part: Or replaces 
those pixels with black pixels, thus "overlaying" the destination with the black 
part of the pattern or source; Xor inverts the pixels under the black part; and 
Bic erases them to white. 


Each of the basic operations has a variant in which every pixel in the pattern 
or source is inverted before the operation is performed, giving eight operations 
in all. Each mode is defined by name as a constant in QuickDraw (see Figure 17). 
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“Overlay “Thvert" "Erase" 
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Figure 17-Transfer Modes 
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Figure 17-Transfer Modes 


Pattern Source Action on each pixel in destination: 
transfer transfer If black pixel in If white pixel in 
mode mode pattern or source pattern or source 
patCopy srcCopy Force black Force white 

patOr srcOr Force black Leave alone 
patXor srcxor Invert Leave alone 
patBic srcBic Force white Leave alone 
notPatCopy notSrcCopy Force white Force black 
notPatOr notSrcOr Leave alone Force black 
notPatXor notSrcXor Leave alone Invert 

notPatBic notSrcBic Leave alone Force white 


Drawing in Color 


Your application can draw on color output devices by using QuickDraw procedures 
to set the foreground color and the background color. Eight standard colors may 
be specified with the following predefined constants: 


CONST blackColor = 33; 
whiteColor = 30; 
redColor = 209; 
greenColor = 329; 
blueColor = 389; 
cyanColor = 269; 
magentaColor = 149; 
yellowColor = 89; 


Initially, the foreground color is blackColor and the background color is 
whiteColor. If you specify a color other than whiteColor, it will appear as 
black on a black-and-white output device. 


To apply the table in the "Transfer Modes" section above to drawing in color, 
make the following translation: Where the table shows "Force black", read 
"Force foreground color", and where it shows "Force white", read "Force 
background color". The effect of inverting a color depends on the device being 
used. 


Note: QuickDraw can support output devices that have up to 32 bits of color 
information per pixel. A color picture may be thought of, then, as 
having up to 32 planes. At any one time, QuickDraw draws into only 
one of these planes. A QuickDraw routine called by the color-imaging 
software specifies which plane. 


eeeClick on the X-Ref button, and refer to Technical Note #73.¢¢« 
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PICTURES AND POLYGONS 


QuickDraw lets you save a sequence of drawing commands and "play them back" 
later with a single procedure call. There are two such mechanisms: one for 
drawing any picture to scale in a destination rectangle that you specify, and 
another for drawing polygons in all the ways you can draw other shapes in 
QuickDraw. 


Pictures 


A picture in QuickDraw is a transcript of calls to routines that draw 
something—anything—in a bit image. Pictures make it easy for one program to draw 
something defined in another program, with great flexibility and without knowing 
the details about what's being drawn. 


For each picture you define, you specify a rectangle that surrounds it; this 
rectangle is called the picture frame. When you later call the procedure that 
plays back the saved picture, you supply a destination rectangle, and QuickDraw 
scales the picture so that its frame is completely aligned with the destination 
rectangle. Thus, the picture may be expanded or shrunk to fit its destination 
rectangle. For example, if the picture is a circle inside a square picture 
frame, and the destination rectangle is not square, the picture will be drawn as 
an oval. 


Since a picture may include any sequence of drawing commands, its data structure 
is a variable-length entity. It consists of two fixed-length fields followed by 
a variable-length field: 


TYPE Picture = RECORD 
picSize: INTEGER; {size in bytes} 


picFrame: Rect; {picture frame} 
{picture definition data} 
END; 


The picSize field contains the size, in bytes, of the picture variable. The 
picFrame field is the picture frame that surrounds the picture and gives a frame 
of reference for scaling when the picture is played back. The rest of the 
structure contains a compact representation of the drawing commands that define 
the picture. 


All pictures are accessed through handles: 


TYPE PicPtr 
PicHandle 


“Picture; 
“PicPtr; 


To define a picture, you call a QuickDraw function that returns a picHandle, and 
then call the drawing routines that define the picture. 


QuickDraw also allows you to intersperse picture comments with the definition of 
a picture. These comments, which do not affect the picture's appearance, may be 
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used to provide additional information about the picture when it's played back. 
This is especially valuable when pictures are transmitted from one application 
to another. There are two standard types of comments which, like parentheses, 
serve to group drawing commands together (such as all the commands that draw a 
particular part of a picture): 


CONST picLParen 
picRParen 


0; 
1; 


The application defining the picture can use these standard comments as well as 
comments of its own design. 


eeeClick on the X-Ref button, and refer to Technical Note #21, #91, & #154.¢+ee 


Polygons 


Polygons are similar to pictures in that you define them by a sequence of calls 
to QuickDraw routines. They're also similar to other shapes that QuickDraw knows 
about, since there's a set of procedures for performing graphic operations and 
calculations on them. 


A polygon is simply any sequence of connected lines (see Figure 18). You define 
a polygon by moving to the starting point of the polygon and drawing lines from 
there to the next point, from that point to the next, and so on. 


The data structure for a polygon consists of two fixed-length fields followed by 
a variable-length array: 


TYPE Polygon = RECORD 
polySize: INTEGER; {size in bytes} 
polyBBox: Rect; {enclosing rectangle} 
polyPoints: ARRAY[0..0] OF Point 
END; 


Figure 18-Polygons 
Figure 18—Polygons 


The polySize field contains the size, in bytes, of the polygon variable. The 
maximum size of a polygon is 32K bytes. The polyBBox field is a rectangle that 
just encloses the entire polygon. The polyPoints array expands as necessary to 
contain the points of the polygon-the starting point followed by each successive 
point to which a line is drawn. 
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Like pictures and regions, polygons are accessed through handles: 


TYPE PolyPtr 
PolyHandle 


“Polygon; 
“PolyPtr; 


To define a polygon, you call a routine that returns a polyHandle, and then call 
the line-drawing routines that define the polygon. 


Just as for other shapes that QuickDraw knows about, there's a set of graphic 
operations to draw polygons on the screen. QuickDraw draws a polygon by moving 
to the starting point and then drawing lines to the remaining points in 
succession, just as when the routines were called to define the polygon. In this 
sense it "plays back" those routine calls. As a result, polygons are not treated 
exactly the same as other QuickDraw shapes. For example, the procedure that 
frames a polygon draws outside the actual boundary of the polygon, because 
QuickDraw line-drawing routines draw below and to the right of the pen location. 
The procedures that fill a polygon with a pattern, however, stay within the 
boundary of the polygon; if the polygon's ending point isn't the same as its 
starting point, these procedures add a line between them to complete the shape. 


QuickDraw also scales a polygon differently from a similarly-shaped region if 
it's being drawn as part of a picture: When stretched, a slanted line is drawn 
more smoothly if it's part of a polygon rather than a region. You may find it 
helpful to keep in mind the conceptual difference between polygons and regions: 
A polygon is treated more as a continuous shape, a region more as a set of bits. 
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USING QUICKDRAW 


Call the InitGraf procedure to initialize QuickDraw at the beginning of your 
program, before initializing any other parts of the Toolbox. 


When your application starts up, the cursor will be a wristwatch; the Finder 
sets it to this to indicate that a lengthy operation is in progress. Call the 
InitCursor procedure when the application is ready to respond to user input, to 
change the cursor to the standard arrow. Each time through the main event loop, 
you should call SetCursor to change the cursor as appropriate for its screen 
location. 


All graphic operations are performed in grafPorts. Before a grafPort can be 
used, it must be allocated and initialized with the OpenPort procedure. 
Normally, you don't call OpenPort yourself—in most cases your application will 
draw into a window you've created with Window Manager routines, and these 
routines call OpenPort to create the window's grafPort. Likewise, a grafPort's 
regions are disposed of with ClosePort, and the grafPort itself is disposed of 
with the Memory Manager procedure DisposPtr—but when you call the Window Manager 
to close or dispose of a window, it calls these routines for you. 


In an application that uses multiple windows, each is a separate grafPort. If 
your application draws into more than one grafPort, you can call SetPort to set 
the grafPort that you want to draw in. At times you may need to preserve the 
current grafPort; you can do this by calling GetPort to save the current port, 
SetPort to set the port you want to draw in, and then SetPort again when you 
need to restore the previous port. 


Each grafPort has its own local coordinate system. Some Toolbox routines return 
or expect points that are expressed in a common, global coordinate system, while 
others use local coordinates. For example, when the Event Manager reports an 
event, it gives the mouse location in global coordinates; but when you call the 
Control Manager to find out whether the user clicked in a control in one of your 
windows, you pass the mouse location in local coordinates. The GlobalToLocal 
procedure lets you convert global coordinates to local coordinates, and the 
LocalToGlobal procedure lets you do the reverse. 


The SetOrigin procedure will adjust a grafPort's local coordinate system. If 
your application performs scrolling, you'll use ScrollRect to shift the bits of 
the image, and then SetOrigin to readjust the coordinate system after this 
shift. 


You can redefine a grafPort's clipping region with the SetClip or ClipRect 
procedure. Just as GetPort and SetPort are used to preserve the current 
grafPort, GetClip and SetClip are useful for saving the grafPort's clipRgn while 
you temporarily perform other clipping functions. This is useful, for example, 
when you want to reset the clipRgn to redraw the newly displayed portion of a 
document that's been scrolled. 


When drawing text in a grafPort, you can set the font characteristics with 
TextFont, TextFace, TextMode, and TextSize. CharWidth, StringWidth, or TextWidth 
will tell you how much horizontal space the text will require, and GetFontInfo 
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will tell you how much vertical space. You can draw text with DrawChar, 
DrawString, and DrawText. 


The LineTo procedure draws a line from the current pen location to a given 
point, and the Line procedure draws a line between two given points. You can set 
the pen location with the MoveTo or Move procedure, and set other pen 
characteristics with PenSize, PenMode, and PenPat. 


In addition to drawing text and lines, you can use QuickDraw to draw a variety 
of shapes. Most of them are defined simply by a rectangle that encloses the 
shape. Others require you to call a series of routines to define them: 


¢ To define a region, call the NewRgn function to allocate space for it, 
then call OpenRgn, and then specify the outline of the region by calling 
routines that draw lines and shapes. End the region definition by calling 
CloseRgn. When you're completely done with the region, call DisposeRgn 
to release the memory it occupies. 

¢ To define a polygon, call the OpenPoly function and then form the polygon 
by calling procedures that draw lines. Call ClosePoly when you're finished 
defining the polygon, and KillPoly when you're completely done with it. 


You can perform the following graphic operations on rectangles, rounded-corner 
rectangles, ovals, arcs/wedges, regions, and polygons: 


frame, to outline the shape using the current pen pattern and size 
paint, to fill the shape using the current pen pattern 

erase, to paint the shape using the current background pattern 
invert, to invert the pixels in the shape 

fill, to fill the shape with a specified pattern 


eeeee 


QuickDraw pictures let you record and play back complex drawing sequences. To 
define a picture, call the OpenPicture function and then the drawing routines 
that form the picture. Call ClosePicture when you're finished defining the 
picture. To draw a picture, call DrawPicture. When you're completely done with a 
picture, call KillPicture (or the Resource Manager procedure ReleaseResource, if 
the picture's a resource). 


You'll use points, rectangles, and regions not only when drawing with QuickDraw, 
but also when using other parts of the Toolbox and Operating System. At times, 
you may find it useful to perform calculations on these entities. You can, for 
example, add and subtract points, and perform a number of calculations on 
rectangles and regions, such as offsetting them, rescaling them, calculating 
their union or intersection, and so on. 


Note: When performing a calculation on entities in different grafPorts, 
you need to adjust to a common coordinate system first, by calling 
LocalToGlobal to convert to global coordinates. 


To transfer a bit image from one bit map to another, you can use the CopyBits 
procedure. For example, you can call SetPortBits to change the bit map of the 
current grafPort to an off-screen buffer, draw into that grafPort, and then call 
CopyBits to transfer the image from the off-screen buffer onto the screen. 


The SeedFill and CalcMask procedures operate on a portion of a bitmap. In both 
routines, srcPtr and dstPtr point to the beginning of the data to be filled or 
calculated, not to the beginning of the bitmap; both parameters must point to 
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word boundaries in memory. SrcRow and dstRow specify the row width in bytes (in 
other words, the rowBytes field of the BitMap record) of the source and 
destination bitmaps respectively. Height and words determine the number of bits 
to be filled or calculated; words is the width of the rectangle in words and 


height is the height of the rectangle in pixels. Figure 19 illustrates the use 
of these parameters. 


" sreRow s , itkow i 
words 
a_i 
sreFtr detPtr 
words 
Leight <4—_—_—_- 

heizht 

source bitmap destination bitmap 


Figure 19-—Parameters Used by Seed Fill and CalcMask 
Figure 19—-Parameters Used by SeedFill and CalcMask 
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QUICKDRAW ROUTINES 


GrafPort Routines 
PROCEDURE InitGraf (globalPtr: Ptr); 
Call InitGraf once and only once at the beginning of your program to initialize 


QuickDraw. It initializes the global variables listed below (as well as some 
private global variables for its own internal use). 


Variable Type Initial setting 

thePort GrafPtr NIL 

white Pattern An all-white pattern 
black Pattern An all-black pattern 

gray Pattern A 50% gray pattern 

LtGray Pattern A 25% gray pattern 

dkGray Pattern A 75% gray pattern 

arrow Cursor The standard arrow cursor 
screenBits BitMap The entire screen 
randSeed LONGINT 1 


You must pass, in the globalPtr parameter, a pointer to the first QuickDraw 
global variable, thePort. From Pascal programs, you should always pass @thePort 
for globalPtr. 


Assembly-language note: The QuickDraw global variables are stored in reverse 
order, from high to low memory, and require the number 
of bytes specified by the global constant grafSize. 
Most development systems (including the Lisa Workshop) 
preallocate space for these globals immediately below 
the location pointed to by register A5. Since thePort 
is four bytes, you would pass the globalPtr parameter 
as follows: 


PEA -4(A5) 
_InitGraf 


InitGraf stores this pointer to thePort in the 
location pointed to by A5. This value is used as a 
base address when accessing the other QuickDraw global 
variables, which are accessed using negative offsets 
(the offsets have the same names as the Pascal global 
variables). For example: 


MOVE.L (A5),A0 ;point to first 
; QuickDraw global 
MOVE.L randSeed(AQ) ,Al ;get global variable 
; randSeed 


Note: To initialize the cursor, call InitCursor (described under 
"Cursor-Handling Routines" below). 
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PROCEDURE OpenPort (port: GrafPtr); 


OpenPort allocates space for the given grafPort's visRgn and clipRgn, 
initializes the fields of the grafPort as indicated below, and makes the 
grafPort the current port (by calling SetPort). OpenPort is called by the Window 
Manager when you create a window, and you normally won't call it yourself. If 
you do call OpenPort, you can create the grafPtr with the Memory Manager 
procedure NewPtr or reserve the space on the stack (with a variable of type 
GrafPort). 


Field Type Initial setting 

device INTEGER 0 (the screen) 

portBits BitMap screenBits 

portRect Rect screenBits.bounds 

visRgn RgnHandle handle to a rectangular region coincident 
with screenBits.bounds 

clipRgn RgnHandle handle to the rectangular region 
(—32767 ,-32767) (32767,32767) 

bkPat Pattern white 

FillPat Pattern black 

pnLoc Point (0,0) 

pnSize Point (1,1) 

pnMode INTEGER patCopy 

pnPat Pattern black 

pnVis INTEGER 0 (visible) 

txFont INTEGER 0 (system font) 

txFace Style plain 

txMode INTEGER srcoOr 

txSize INTEGER 0 (system font size) 

spExtra Fixed 0 

fgColor LONGINT blackColor 

bkColor LONGINT whiteColor 

colrBit INTEGER 0 

patStretch INTEGER 0 

picSave Handle NIL 

rgnSave Handle NIL 

polySave Handle NIL 

grafProcs QDProcsPtr NIL 


PROCEDURE InitPort (port: GrafPtr); 


Given a pointer to a grafPort that's been opened with OpenPort, InitPort 
reinitializes the fields of the grafPort and makes it the current port. It's 
unlikely that you'll ever have a reason to call this procedure. 


Note: InitPort does everything OpenPort does except allocate space for 
the visRgn and clipRgn. 


PROCEDURE ClosePort (port: GrafPtr); 
ClosePort releases the memory occupied by the given grafPort's visRgn and 


clipRgn. When you're completely through with a grafPort, call this procedure and 
then dispose of the grafPort with the Memory Manager procedure DisposPtr 
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(if it was allocated with NewPtr). This is normally done for you when you call 
the Window Manager to close or dispose of a window. 


Warning: If ClosePort isn't called before a grafPort is disposed of, the 
memory used by the visRgn and clipRgn will be unrecoverable. 


PROCEDURE SetPort (port: GrafPtr); 
SetPort makes the specified grafPort the current port. 


Note: Only SetPort (and OpenPort and InitPort, which call it) changes the 
current port. All the other routines in the Toolbox and Operating 
System (even those that call SetPort, OpenPort, or InitPort) leave 
the current port set to what it was when they were called. 


The global variable thePort always points to the current port. All QuickDraw 
drawing routines affect the bit map thePort*.portBits and use the local 
coordinate system of thePort’. 


Each port has its own pen and text characteristics, which remain unchanged when 
the port isn't selected as the current port. 


PROCEDURE GetPort (VAR port: GrafPtr); 


GetPort returns a pointer to the current grafPort. This pointer is also 
available through the global variable thePort, but you may prefer to use GetPort 
for better readability of your program text. For example, a procedure could do a 
GetPort(savePort) before setting its own grafPort and a 

SetPort(savePort) afterwards to restore the previous port. 


PROCEDURE GrafDevice (device: INTEGER); 


GrafDevice sets the device field of the current grafPort to the given value, 
which consists of device-specific information that's used by the Font Manager to 
achieve the best possible results when drawing text in the grafPort. The initial 
value of the device field is 0, for best results on output to the screen. For 
more information, see the Font Manager chapter. 


Note: This field is used for communication between QuickDraw and the Font 
Manager; normally you won't set it yourself. 


PROCEDURE SetPortBits (bm: BitMap); 


Assembly-language note: The macro you invoke to call SetPortBits from 
assembly Language is named SetPBits. 


SetPortBits sets the portBits field of the current grafPort to any previously 
defined bit map. This allows you to perform all normal drawing and calculations 
on a buffer other than the screen—for example, a small off-screen image for 
later "stamping" onto the screen (with the CopyBits procedure, described under 
"Bit Transfer Operations" below). 


Remember to prepare all fields of the bit map before you call SetPortBits. 


PROCEDURE PortSize (width,height: INTEGER); 
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PortSize changes the size of the current grafPort's portRect. This does not 
affect the screen; it merely changes the size of the "active area" of the 
grafPort. 


Note: This procedure is normally called only by the Window Manager. 


The top left corner of the portRect remains at its same location; the width and 
height of the portRect are set to the given width and height. In other words, 
PortSize moves the bottom right corner of the portRect to a position relative to 
the top left corner. 


PortSize doesn't change the clipRgn or the visRgn, nor does it affect the local 
coordinate system of the grafPort: It changes only the portRect's width and 
height. Remember that all drawing occurs only in the intersection of the 
portBits.bounds and the portRect, clipped to the visRgn and the clipRgn. 


PROCEDURE MovePortTo (leftGlobal,topGlobal: INTEGER); 


MovePortTo changes the position of the current grafPort's portRect. This does 
not affect the screen; it merely changes the location at which subsequent 
drawing inside the port will appear. 


Note: This procedure is normally called only by the Window Manager 
and the System Error Handler. 


The leftGlobal and topGlobal parameters set the distance between the top left 
corner of portBits.bounds and the top left corner of the new portRect. 


Like PortSize, MovePortTo doesn't change the clipRgn or the visRgn, nor does it 
affect the local coordinate system of the grafPort. 


PROCEDURE SetOrigin (h,v: INTEGER); 


SetOrigin changes the local coordinate system of the current grafPort. This does 
not affect the screen; it does, however, affect where subsequent drawing inside 
the port will appear. 


The h and v parameters set the coordinates of the top left corner of the 
portRect. All other coordinates are calculated from this point; SetOrigin also 
offsets the coordinates of the portBits.bounds rectangle and the visRgn. 
Relative distances among elements in the port remain the same; only their 
absolute local coordinates change. All subsequent drawing and calculation 
routines use the new coordinate system. 


Note: SetOrigin does not offset the coordinates of the clipRgn or the pen; 
the pen and clipRgn "stick" to the coordinate system, and therefore 
change position on the screen (unlike the portBits.bounds, portRect, 
and visRgn, which "stick" to the screen, and don't change position). 
See the "Coordinates in GrafPorts" section for an illustration. 


SetOrigin is useful for readjusting the coordinate system after a scrolling 
operation. (See ScrollRect under "Bit Transfer Operations" below. ) 


Note: All other routines in the Toolbox and Operating System preserve the 
local coordinate system of the current grafPort. 
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PROCEDURE SetClip (rgn: RgnHandle); 


SetClip changes the clipping region of the current grafPort to a region that's 
equivalent to the given region. Note that this doesn't change the region handle, 
but affects the clipping region itself. Since SetClip makes a copy of the given 
region, any subsequent changes you make to that region will not affect the 
clipping region of the port. 


You can set the clipping region to any arbitrary region, to aid you in drawing 
inside the grafPort. The initial clipRgn is an arbitrarily large rectangle. 


Note: All routines in the Toolbox and Operating System preserve the 
current clipRgn. 


PROCEDURE GetClip (rgn: RgnHandle); 


GetClip changes the given region to a region that's equivalent to the clipping 
region of the current grafPort. This is the reverse of what SetClip does. Like 
SetClip, it doesn't change the region handle. GetClip and SetClip are used to 

preserve the current clipRgn (they're analogous to GetPort and SetPort). 


PROCEDURE ClipRect (r: Rect); 

ClipRect changes the clipping region of the current grafPort to a rectangle 
that's equivalent to the given rectangle. Note that this doesn't change the 
region handle, but affects the clipping region itself. 

PROCEDURE BackPat (pat: Pattern); 

BackPat sets the background pattern of the current grafPort to the given 


pattern. The background pattern is used in ScrollRect and in all QuickDraw 
routines that perform an "erase" operation. 


Cursor-Handling Routines 
PROCEDURE InitCursor; 


InitCursor sets the current cursor to the standard arrow and sets the cursor 
level to 0, making the cursor visible. The cursor level keeps track of the 
number of times the cursor has been hidden to compensate for nested calls to 
HideCursor and ShowCursor, explained below. 


PROCEDURE SetCursor (crsr: Cursor); 


SetCursor sets the current cursor to the given cursor. If the cursor is hidden, 
it remains hidden and will attain the new appearance when it's uncovered; if the 
cursor is already visible, it changes to the new appearance immediately. 


The cursor image is initialized by InitCursor to the standard arrow, visible on 
the screen. 


Note: You'll normally get a cursor from a resource file, by calling the 
Toolbox Utility function GetCursor, and then doubly dereference the 
handle it returns. 
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PROCEDURE HideCursor; 


HideCursor removes the cursor from the screen, restoring the bits under it, and 
decrements the cursor level (which InitCursor initialized to 0). Every call to 
HideCursor should be balanced by a subsequent call to ShowCursor. 


Note: See also the description of the Toolbox Utility procedure ShieldCursor. 
PROCEDURE ShowCursor; 


ShowCursor increments the cursor level, which may have been decremented by 
HideCursor, and displays the cursor on the screen if the level becomes 0. A call 
to ShowCursor should balance each previous call to HideCursor. The level isn't 
incremented beyond 0, so extra calls to ShowCursor have no effect. 


The low-level interrupt-driven routines link the cursor with the mouse position, 
so that if the cursor level is 0 (visible), the cursor automatically follows the 
mouse. You don't need to do anything but a ShowCursor to have the cursor track 
the mouse. 


If the cursor has been changed (with SetCursor) while hidden, ShowCursor 
presents the new cursor. 


PROCEDURE ObscureCursor; 
ObscureCursor hides the cursor until the next time the mouse is moved. It's 


normally called when the user begins to type. Unlike HideCursor, it has no 
effect on the cursor level and must not be balanced by a call to ShowCursor. 


Pen and Line-Drawing Routines 


The pen and line-drawing routines all depend on the coordinate system of the 
current grafPort. Remember that each grafPort has its own pen; if you draw in 
one grafPort, change to another, and return to the first, the pen will remain in 
the same location. 


PROCEDURE HidePen; 


HidePen decrements the current grafPort's pnVis field, which is initialized to 0 
by OpenPort; whenever pnVis is negative, the pen doesn't draw on the screen. 
PnVis keeps track of the number of times the pen has been hidden to compensate 
for nested calls to HidePen and ShowPen (below). Every call to HidePen should be 
balanced by a subsequent call to ShowPen. HidePen is called by OpenRgn, 
OpenPicture, and OpenPoly so that you can define regions, pictures, and polygons 
without drawing on the screen. 


PROCEDURE ShowPen; 


ShowPen increments the current grafPort's pnVis field, which may have been 
decremented by HidePen; if pnVis becomes 0, QuickDraw resumes drawing on the 
screen. Extra calls to ShowPen will increment pnVis beyond 0, so every call to 
ShowPen should be balanced by a call to HidePen. ShowPen is called by CloseRgn, 
ClosePicture, and ClosePoly. 
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PROCEDURE GetPen (VAR pt: Point); 


GetPen returns the current pen location, in the local coordinates of the current 
grafPort. 


PROCEDURE GetPenState (VAR pnState: PenState); 


GetPenState saves the pen location, size, pattern, and mode in pnState, to be 
restored later with SetPenState. This is useful when calling subroutines that 
operate in the current port but must change the graphics pen: Each such 
procedure can save the pen's state when it's called, do whatever it needs to do, 
and restore the previous pen state immediately before returning. The PenState 
data type is defined as follows: 


TYPE PenState = RECORD 
pnLoc: Point; {pen location} 
pnSize: Point; {pen size} 


pnMode: INTEGER; {pen's transfer mode} 
pnPat: Pattern {pen pattern} 
END; 


PROCEDURE SetPenState (pnState: PenState); 


SetPenState sets the pen location, size, pattern, and mode in the current 
grafPort to the values stored in pnState. This is usually called at the end of a 
procedure that has altered the pen parameters and wants to restore them to their 
state at the beginning of the procedure. (See GetPenState, above. ) 


PROCEDURE PenSize (width,height: INTEGER); 


PenSize sets the dimensions of the graphics pen in the current grafPort. All 
subsequent calls to Line, LineTo, and the procedures that draw framed shapes in 
the current grafPort will use the new pen dimensions. 


The pen dimensions can be accessed in the variable thePort*.pnSize, which is of 
type Point. If either of the pen dimensions is set to a negative value, the pen 
assumes the dimensions (0,0) and no drawing is performed. For a discussion of 
how the pen draws, see the "General Discussion of Drawing" section. 


PROCEDURE PenMode (mode: INTEGER); 

PenMode sets the transfer mode through which the pen pattern is transferred onto 
the bit map when lines or shapes are drawn in the current grafPort. The mode may 
be any one of the pattern transfer modes: 


patCopy notPatCopy 


patOr notPatOr 
patXor notPatXor 
patBic notPatBic 


If the mode is one of the source transfer modes (or negative), no drawing is 
performed. The current pen mode can be accessed in the variable thePort’.pnMode. 
The initial pen mode is patCopy, in which the pen pattern is copied directly to 
the bit map. 
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PROCEDURE PenPat (pat: Pattern); 


PenPat sets the pattern that's used by the pen in the current grafPort. The 
standard patterns white, black, gray, ltGray, and dkGray are predefined; the 
initial pen pattern is black. The current pen pattern can be accessed in the 
variable thePort’*.pnPat, and this value can be assigned to any other variable of 
type Pattern. 


PROCEDURE PenNormal; 


PenNormal resets the initial state of the pen in the current grafPort, as 
follows: 


Field Setting 


pnSize (1,1) 
pnMode patCopy 
pnPat black 


The pen location is not changed. 
PROCEDURE MoveTo (h,v: INTEGER); 


MoveTo moves the pen to location (h,v) in the local coordinates of the current 
grafPort. No drawing is performed. 


PROCEDURE Move (dh,dv: INTEGER); 


This procedure moves the pen a distance of dh horizontally and dv vertically 
from its current location; it calls MoveTo(h+dh,v+dv), where (h,v) is the 
current location. The positive directions are to the right and down. No drawing 
is performed. 


PROCEDURE LineTo (h,v: INTEGER); 


LineTo draws a line from the current pen location to the location specified (in 
local coordinates) by h and v. The new pen location is (h,v) after the line is 
drawn. See the "General Discussion of Drawing" section. 


If a region or polygon is open and being formed, its outline is infinitely thin 
and is not affected by the pnSize, pnMode, or pnPat. (See OpenRgn and OpenPoly. ) 


PROCEDURE Line (dh,dv: INTEGER); 


This procedure draws a line to the location that's a distance of dh horizontally 
and dv vertically from the current pen location; it calls 

LineTo(h+dh,v+dv), where (h,v) is the current location. The positive directions 
are to the right and down. The pen location becomes the coordinates of the end 
of the line after the line is drawn. See the "General Discussion of Drawing" 
section. 


If a region or polygon is open and being formed, its outline is infinitely thin 
and is not affected by the pnSize, pnMode, or pnPat. (See OpenRgn and OpenPoly. ) 
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Text-Drawing Routines 


Each grafPort has its own text characteristics, and all these procedures deal 
with those of the current port. 


PROCEDURE TextFont (font: INTEGER); 


TextFont sets the current grafPort's font (thePort*.txFont) to the given font 
number. The initial font number is 0, which represents the system font. 


PROCEDURE TextFace (face: Style); 


TextFace sets the current grafPort's character style (thePort*.txFace). The 
Style data type allows you to specify a set of one or more of the following 
predefined constants: bold, italic, underline, outline, shadow, condense, and 
extend. For example: 


TextFace([bold]); {bold} 
TextFace([bold,italic]); {bold and italic} 
TextFace(thePort*.txFace+[bold]); {whatever it was plus bold} 
TextFace(thePort*.txFace-[bold]); {whatever it was but not bold} 
TextFace([]); {plain text} 


PROCEDURE TextMode (mode: INTEGER); 


TextMode sets the current grafPort's transfer mode for drawing text 
(thePort*.txMode). The mode should be srcOr, srcXor, or srcBic. The initial 
transfer mode for drawing text is srcOr. 


PROCEDURE TextSize (size: INTEGER); 


TextSize sets the current grafPort's font size (thePort*.txSize) to the given 
number of points. Any size may be specified, but the result will look best if 
the Font Manager has the font in that size (otherwise it will scale a size it 
does have). The next best result will occur if the given size is an even 
multiple of a size available for the font. If 0 is specified, the system font 
size (12 points) will be used. The initial txSize setting is 0. 


PROCEDURE SpaceExtra (extra: Fixed); 


SpaceExtra sets the current grafPort's spExtra field, which specifies the 
average number of pixels by which to widen each space in a line of text. This is 
useful when text is being fully justified (that is, aligned with both a left and 
a right margin). The initial spExtra setting is 0. 


SpaceExtra will also accept a negative parameter, but be careful not to narrow 
Spaces so much that the text is unreadable. 


PROCEDURE DrawChar (ch: CHAR); 

DrawChar places the given character to the right of the pen location, with the 
left end of its base line at the pen's location, and advances the pen 
accordingly. If the character isn't in the font, the font's missing symbol is 
drawn. 


Note: If you're drawing a series of characters, it's faster to make one 
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DrawString or DrawText call rather than a series of DrawChar calls. 
PROCEDURE DrawString (s: Str255); 


DrawString calls DrawChar for each character in the given string. The string is 
placed beginning at the current pen location and extending right. No formatting 
(such as carriage returns and line feeds) is performed by QuickDraw. The pen 
location ends up to the right of the last character in the string. 


Warning: QuickDraw temporarily stores on the stack all of the text you 
ask it to draw, even if the text will be clipped. When drawing 
large font sizes or complex style variations, it's best to draw 
only what will be visible on the screen. You can determine how 
many characters will actually fit on the screen by calling the 
StringWidth function before calling DrawString. 


PROCEDURE DrawText (textBuf: Ptr; firstByte,byteCount: INTEGER); 


DrawText calls DrawChar for each character in the arbitrary structure in memory 
specified by textBuf, starting firstByte bytes into the structure and continuing 
for byteCount bytes (firstByte starts at 0). The text is placed beginning at the 
current pen location and extending right. No formatting (such as carriage 
returns and line feeds) is performed by QuickDraw. The pen location ends up to 
the right of the last character in the string. 


Warning: Inside a picture definition, DrawText can't have a byteCount 
greater than 255. 


Note: You can determine how many characters will actually fit on the 
screen by calling the TextWidth function before calling DrawText. 
(See the warning under DrawString above. ) 


FUNCTION CharWidth (ch: CHAR) : INTEGER; 


CharWidth returns the character width of the specified character, that is, the 
value that will be added to the pen horizontal coordinate if the specified 
character is drawn. CharWidth includes the effects of the stylistic variations 
set with TextFace; if you change these after determining the character width but 
before actually drawing the character, the predetermined width may not be 
correct. If the character is a space, CharWidth also includes the effect of 
SpaceExtra. 


FUNCTION StringWidth (s: Str255) : INTEGER; 


StringWidth returns the width of the given text string, which it calculates by 
adding the CharwWidths of all the characters in the string (see above). 


FUNCTION TextWidth (textBuf: Ptr; firstByte,byteCount: INTEGER) : INTEGER; 


TextWidth returns the width of the text stored in the arbitrary structure in 
memory specified by textBuf, starting firstByte bytes into the structure and 
continuing for byteCount bytes (firstByte starts at 0). TextWidth calculates the 
width by adding the CharWidths of all the characters in the text. (See 
Charwidth, above. ) 


PROCEDURE MeasureText (count: INTEGER; textAddr,charLocs: Ptr); 
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This procedure is designed to improve performance in specialized applications 
such as word processors by providing an array version of the TextWidth function; 
it's like calling TextWidth repeatedly for a given set of characters. TextAddr 
points to an arbitrary piece of text in memory, and count specifies how many 
characters are to be measured. 


MeasureText moves along the string and, for each character, computes the 
distance from TextAddr to the right edge of the character. CharLocs should point 
to an array of count + 1 integers. Upon return, the first element in the array 
will always contain 0; the other elements will contain pixel positions on the 
screen for all of the specified characters. 


Note: MeasureText only works with text displayed on the screen; since it 
doesn't go through the QuickDraw procedure StdText, it can't be used 
to measure text to be printed. 


PROCEDURE GetFontInfo (VAR info: FontInfo); 


GetFontInfo returns the following information about the current grafPort's 
character font, taking into consideration the style and size in which the 
characters will be drawn: the ascent, descent, maximum character width (the 
greatest distance the pen will move when a character is drawn), and leading 
(the vertical distance between the descent line and the ascent Line below it), 
all in pixels. The FontInfo data type is defined as follows: 


TYPE FontInfo = RECORD 
ascent: INTEGER; {ascent} 
descent: INTEGER; {descent} 
widMax: INTEGER; {maximum character width} 
leading: INTEGER {leading} 
END; 


The line height (in pixels) can be determined by adding the ascent, descent, and 
leading. 


Drawing in Color 


These routines enable applications to do color drawing on color output devices. 
ALL nonwhite colors will appear as black on black-and-white output devices. 


PROCEDURE ForeColor (color: LONGINT); 


ForeColor sets the foreground color for all drawing in the current grafPort 
(thePort*.fgColor) to the given color. The following standard colors are 
predefined: blackColor, whiteColor, redColor, greenColor, blueColor, cyanColor, 
magentaColor, and yellowColor. The initial foreground color is blackColor. 


PROCEDURE BackColor (color: LONGINT); 
BackColor sets the background color for all drawing in the current grafPort 


(thePort*.bkColor) to the given color. Eight standard colors are predefined 
(see ForeColor above). The initial background color is whiteColor. 
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PROCEDURE ColorBit (whichBit: INTEGER); 


ColorBit is called by printing software for a color printer, or other color- 
imaging software, to set the current grafPort's colrBit field to whichBit; this 
tells QuickDraw which plane of the color picture to draw into. QuickDraw will 
draw into the plane corresponding to bit number whichBit. Since QuickDraw can 
Support output devices that have up to 32 bits of color information per pixel, 
the possible range of values for whichBit is @ through 31. The initial value of 
the colrBit field is 0. 


Calculations with Rectangles 


Calculation routines are independent of the current coordinate system; a 
calculation will operate the same regardless of which grafPort is active. 


Remember that if the parameters to a calculation procedure were defined in 
different grafPorts, you must first adjust them to global coordinates. 


PROCEDURE SetRect (VAR r: Rect; left,top,right,bottom: INTEGER); 


SetRect assigns the four boundary coordinates to the given rectangle. The result 
is a rectangle with coordinates (left,top) (right,bottom). 


This procedure is supplied as a utility to help you shorten your program text. 
If you want a more readable text at the expense of length, you can assign 
integers (or points) directly into the rectangle's fields. There's no 
Significant code size or execution speed advantage to either method. 


PROCEDURE OffsetRect (VAR r: Rect; dh,dv: INTEGER); 


OffsetRect moves the given rectangle by adding dh to each horizontal coordinate 
and dv to each vertical coordinate. If dh and dv are positive, the movement is 
to the right and down; if either is negative, the corresponding movement is in 
the opposite direction. The rectangle retains its shape and size; it's merely 
moved on the coordinate plane. This doesn't affect the screen unless you 
subsequently call a routine to draw within the rectangle. 


PROCEDURE InsetRect (VAR r: Rect; dh,dv: INTEGER); 


InsetRect shrinks or expands the given rectangle. The left and right sides are 
moved in by the amount specified by dh; the top and bottom are moved toward the 
center by the amount specified by dv. If dh or dv is negative, the appropriate 
pair of sides is moved outward instead of inward. The effect is to alter the 
size by 2*dh horizontally and 2*dv vertically, with the rectangle remaining 
centered in the same place on the coordinate plane. 


If the resulting width or height becomes less than 1, the rectangle is set to 
the empty rectangle (0,0)(0,0). 


FUNCTION SectRect (srcl,src2: Rect; VAR dstRect: Rect) : BOOLEAN; 
SectRect calculates the rectangle that's the intersection of the two given 


rectangles, and returns TRUE if they indeed intersect or FALSE if they don't. 
Rectangles that "touch" at a line or a point are not considered intersecting, 
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because their intersection rectangle (actually, in this case, an intersection 
line or point) doesn't enclose any bits in the bit image. 


If the rectangles don't intersect, the destination rectangle is set to (0,0) 
(0,0). SectRect works correctly even if one of the source rectangles is also the 
destination. 


PROCEDURE UnionRect (srcl,src2: Rect; VAR dstRect: Rect); 


UnionRect calculates the smallest rectangle that encloses both of the given 
rectangles. It works correctly even if one of the source rectangles is also the 
destination. 


FUNCTION PtInRect (pt: Point; r: Rect) : BOOLEAN; 


PtInRect determines whether the pixel below and to the right of the given 
coordinate point is enclosed in the specified rectangle, and returns TRUE if so 
or FALSE if not. 


PROCEDURE Pt2Rect (ptl,pt2: Point; VAR dstRect: Rect); 
Pt2Rect returns the smallest rectangle that encloses the two given points. 
PROCEDURE PtToAngle (r: Rect; pt: Point; VAR angle: INTEGER); 


PtToAngle calculates an integer angle between a line from the center of the 
rectangle to the given point and a line from the center of the rectangle 
pointing straight up (12 o'clock high). The angle is in degrees from 0 to 359, 
measured clockwise from 12 o'clock, with 90 degrees at 3 o'clock, 180 at 

6 o'clock, and 270 at 9 o'clock. Other angles are measured relative to the 
rectangle: If the line to the given point goes through the top right corner of 
the rectangle, the angle returned is 45 degrees, even if the rectangle isn't 
square; if it goes through the bottom right corner, the angle is 135 degrees, 
and so on (see Figure 20). 


Figure 20-PtToAngle 
Figure 20—PtToAngle 
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The angle returned might be used as input to one of the procedures that 
manipulate arcs and wedges, as described below under "Graphic Operations on Arcs 
and Wedges". 


FUNCTION EqualRect (rectl,rect2: Rect) : BOOLEAN; 

EqualRect compares the two given rectangles and returns TRUE if they're equal or 
FALSE if not. The two rectangles must have identical boundary coordinates to be 
considered equal. 

FUNCTION EmptyRect (r: Rect) : BOOLEAN; 

EmptyRect returns TRUE if the given rectangle is an empty rectangle or FALSE if 


not. A rectangle is considered empty if the bottom coordinate is less than or 
equal to the top or the right coordinate is less than or equal to the left. 


Graphic Operations on Rectangles 
See also the ScrollRect procedure under "Bit Transfer Operations". 
PROCEDURE FrameRect (r: Rect); 


FrameRect draws an outline just inside the specified rectangle, using the 
current grafPort's pen pattern, mode, and size. The outline is as wide as the 
pen width and as tall as the pen height. It's drawn with the pnPat, according to 
the pattern transfer mode specified by pnMode. The pen location is not changed 
by this procedure. 


If a region is open and being formed, the outside outline of the new rectangle 
is mathematically added to the region's boundary. 


PROCEDURE PaintRect (r: Rect); 

PaintRect paints the specified rectangle with the current grafPort's pen pattern 
and mode. The rectangle is filled with the pnPat, according to the pattern 
transfer mode specified by pnMode. The pen location is not changed by this 
procedure. 

PROCEDURE EraseRect (r: Rect); 

EraseRect paints the specified rectangle with the current grafPort's background 
pattern bkPat (in patCopy mode). The grafPort's pnPat and pnMode are ignored; 
the pen location is not changed. 

PROCEDURE InvertRect (r: Rect); 


Assembly-language note: The macro you invoke to call InvertRect from 
assembly Language is named InverRect. 


InvertRect inverts the pixels enclosed by the specified rectangle: Every white 
pixel becomes black and every black pixel becomes white. The grafPort's pnPat, 
pnMode, and bkPat are all ignored; the pen location is not changed. 


PROCEDURE FillRect (r: Rect; pat: Pattern); 
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FillRect fills the specified rectangle with the given pattern (in patCopy mode). 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is not 
changed. 


Graphic Operations on Ovals 


Ovals are drawn inside rectangles that you specify. If you specify a square 
rectangle, QuickDraw draws a circle. 


PROCEDURE FrameOval (r: Rect); 


FrameOval draws an outline just inside the oval that fits inside the specified 
rectangle, using the current grafPort's pen pattern, mode, and size. The outline 
is as wide as the pen width and as tall as the pen height. It's drawn with the 
pnPat, according to the pattern transfer mode specified by pnMode. The pen 
location is not changed by this procedure. 


If a region is open and being formed, the outside outline of the new oval is 
mathematically added to the region's boundary. 


PROCEDURE PaintOval (r: Rect); 


PaintOval paints an oval just inside the specified rectangle with the current 
grafPort's pen pattern and mode. The oval is filled with the pnPat, according to 
the pattern transfer mode specified by pnMode. The pen location is not changed 
by this procedure. 


PROCEDURE EraseOval (r: Rect); 


EraseOval paints an oval just inside the specified rectangle with the current 
grafPort's background pattern bkPat (in patCopy mode). The grafPort's pnPat and 
pnMode are ignored; the pen location is not changed. 


PROCEDURE InvertOval (r: Rect); 


InvertOval inverts the pixels enclosed by an oval just inside the specified 
rectangle: Every white pixel becomes black and every black pixel becomes white. 
The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is not 
changed. 


PROCEDURE FillOval (r: Rect; pat: Pattern); 
FillOval fills an oval just inside the specified rectangle with the given 


pattern (in patCopy mode). The grafPort's pnPat, pnMode, and bkPat are all 
ignored; the pen location is not changed. 


Graphic Operations on Rounded-Corner Rectangles 


PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
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FrameRoundRect draws an outline just inside the specified rounded-corner 
rectangle, using the current grafPort's pen pattern, mode, and size. OvalWidth 
and ovalHeight specify the diameters of curvature for the corners (see Figure 
21). The outline is as wide as the pen width and as tall as the pen height. 
It's drawn with the pnPat, according to the pattern transfer mode specified by 
pnMode. The pen location is not changed by this procedure. 


oval Width ovelHeight 


Figure 21—Rounded-Comer Rectangle 
Figure 21—Rounded-Corner Rectangle 


If a region is open and being formed, the outside outline of the new rounded- 
corner rectangle is mathematically added to the region's boundary. 


PROCEDURE PaintRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 
PaintRoundRect paints the specified rounded-corner rectangle with the current 
grafPort's pen pattern and mode. OvalWidth and ovalHeight specify the diameters 
of curvature for the corners. 

The rounded-corner rectangle is filled with the pnPat, according to the pattern 
transfer mode specified by pnMode. The pen location is not changed by this 
procedure. 

PROCEDURE EraseRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


EraseRoundRect paints the specified rounded-corner rectangle with the current 
grafPort's background pattern bkPat (in patCopy mode). 


OvalWidth and ovalHeight specify the diameters of curvature for the corners. The 
grafPort's pnPat and pnMode are ignored; the pen location is not changed. 


PROCEDURE InvertRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 


Assembly-language note: The macro you invoke to call InvertRoundRect from 
assembly Language is named InverRoundRect. 
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InvertRoundRect inverts the pixels enclosed by the specified rounded-corner 
rectangle: Every white pixel becomes black and every black pixel becomes white. 
OvalWidth and ovalHeight specify the diameters of curvature for the corners. The 
grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is not 
changed. 


PROCEDURE FillRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER; 
pat: Pattern); 


FillRoundRect fills the specified rounded-corner rectangle with the given 
pattern (in patCopy mode). OvalWidth and ovalHeight specify the diameters of 
curvature for the corners. The grafPort's pnPat, pnMode, and bkPat are all 
ignored; the pen location is not changed. 


Graphic Operations on Arcs and Wedges 


These procedures perform graphic operations on arcs and wedge-shaped sections of 
ovals. See also PtToAngle under "Calculations with Rectangles". 


PROCEDURE FrameArc (r: Rect; startAngle,arcAngle: INTEGER); 


FrameArc draws an arc of the oval that fits inside the specified rectangle, 
using the current grafPort's pen pattern, mode, and size. StartAngle indicates 
where the arc begins and is treated MOD 360. ArcAngle defines the extent of the 
arc. The angles are given in positive or negative degrees; a positive angle goes 
clockwise, while a negative angle goes counterclockwise. Zero degrees is at 12 
o'clock high, 90 (or —270) is at 3 o'clock, 180 (or —180) is at 6 o'clock, and 
270 (or —90) is at 9 o'clock. Other angles are measured relative to the 
enclosing rectangle: A line from the center of the rectangle through its top 
right corner is at 45 degrees, even if the rectangle isn't square; a line 
through the bottom right corner is at 135 degrees, and so on (see Figure 22). 


startainele= 0 
startAngle= 0 startAmele= arcAngle= 45 
Framesre 
startAngle= 0 
arcAmele= 45 
Framezure 
Paint Are 


Figure 22-Operations on Arcs and Wedges 


Figure 22—Operations on Arcs and Wedges 
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The arc is as wide as the pen width and as tall as the pen height. It's drawn 
with the pnPat, according to the pattern transfer mode specified by pnMode. The 
pen location is not changed by this procedure. 


Warning: FrameArc differs from other QuickDraw routines that frame shapes 
in that the arc is not mathematically added to the boundary of a 
region that's open and being formed. 


Note: QuickDraw doesn't provide a routine for drawing an outlined wedge 
of an oval. 


PROCEDURE PaintArc (r: Rect; startAngle,arcAngle: INTEGER); 


PaintArc paints a wedge of the oval just inside the specified rectangle with the 
current grafPort's pen pattern and mode. StartAngle and arcAngle define the arc 
of the wedge as in FrameArc. The wedge is filled with the pnPat, according to 
the pattern transfer mode specified by pnMode. The pen location is not changed 
by this procedure. 


PROCEDURE EraseArc (r: Rect; startAngle,arcAngle: INTEGER); 


EraseArc paints a wedge of the oval just inside the specified rectangle with the 
current grafPort's background pattern bkPat (in patCopy mode). StartAngle and 
arcAngle define the arc of the wedge as in FrameArc. The grafPort's pnPat and 
pnMode are ignored; the pen location is not changed. 


PROCEDURE InvertArc (r: Rect; startAngle,arcAngle: INTEGER); 


InvertArc inverts the pixels enclosed by a wedge of the oval just inside the 
specified rectangle: Every white pixel becomes black and every black pixel 
becomes white. StartAngle and arcAngle define the arc of the wedge as in 
FrameArc. The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen 
location is not changed. 


PROCEDURE FillArc (r: Rect; startAngle,arcAngle: INTEGER; pat: Pattern); 


FillArc fills a wedge of the oval just inside the specified rectangle with the 
given pattern (in patCopy mode). StartAngle and arcAngle define the arc of the 
wedge as in FrameArc. The grafPort's pnPat, pnMode, and bkPat are all ignored; 
the pen location is not changed. 


Calculations with Regions 


Remember that if the parameters to a calculation procedure were defined in 
different grafPorts, you must first adjust them to global coordinates. 


FUNCTION NewRgn : RgnHandle; 

NewRgn allocates space for a new, variable-size region, initializes it to the 
empty region defined by the rectangle (0,0)(0,0), and returns a handle to the 
new region. 


Warning: Only this function creates new regions; all other routines just 
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alter the size and shape of existing regions. Before a region's 
handle can be passed to any drawing or calculation routine, space 
must already have been allocated for the region. 


PROCEDURE OpenRgn; 


OpenRgn tells QuickDraw to allocate temporary space and start saving lines and 
framed shapes for later processing as a region definition. While a region is 
open, all calls to Line, LineTo, and the procedures that draw framed shapes 
(except arcs) affect the outline of the region. Only the line endpoints and 
shape boundaries affect the region definition; the pen mode, pattern, and size 
do not affect it. In fact, OpenRgn calls HidePen, so no drawing occurs on the 
screen while the region is open (unless you called ShowPen just after OpenRgn, 
or you called ShowPen previously without balancing it by a call to HidePen). 
Since the pen hangs below and to the right of the pen location, drawing lines 
with even the smallest pen will change bits that lie outside the region you 
define. 


The outline of a region is mathematically defined and infinitely thin, and 
separates the bit image into two groups of bits: Those within the region and 
those outside it. A region should consist of one or more closed loops. Each 
framed shape itself constitutes a loop. Any lines drawn with Line or LineTo 
should connect with each other or with a framed shape. Even though the on-screen 
presentation of a region is clipped, the definition of a region is not; you can 
define a region anywhere on the coordinate plane with complete disregard for the 
location of various grafPort entities on that plane. 


When a region is open, the current grafPort's rgnSave field contains a handle to 
information related to the region definition. If you want to temporarily disable 
the collection of lines and shapes, you can save the current value of this 
field, set the field to NIL, and later restore the saved value to resume the 
region definition. Also, calling SetPort while a region is being formed will 
discontinue formation of the region until another call to SetPort resets the 
region's original grafPort. 


Warning: Do not call OpenRgn while another region or polygon is already 
open. ALl open regions but the most recent will behave strangely. 


Note: Regions are limited to 32K bytes. 
PROCEDURE CloseRgn (dstRgn: RgnHandle) ; 


CloseRgn stops the collection of lines and framed shapes, organizes them into a 
region definition, and saves the resulting region in the region indicated by 
dstRgn. CloseRgn does not create the destination region; space must already have 
been allocated for it. You should perform one and only one CloseRgn for every 
OpenRgn. CloseRgn calls ShowPen, balancing the HidePen call made by OpenRgn. 


Here's an example of how to create and open a region, define a barbell shape, 
close the region, draw it, and dispose of it: 


barbell := NewRgn; {create a new region} 
OpenRgn; {begin collecting stuff} 
SetRect (tempRect,20,20,30,50); {form the left weight} 
FrameOval(tempRect) ; 
SetRect (tempRect,25,30,85,40) ; {form the bar} 
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FrameRect(tempRect) ; 


SetRect (tempRect,80,20,90,50); {form the right weight} 
FrameOval(tempRect) ; 
CloseRgn(barbell) ; {we're done; save in barbell} 
FillRgn(barbell, black) ; {draw it on the screen} 
DisposeRgn(barbell) {dispose of the region} 


PROCEDURE DisposeRgn (rgn: RgnHandle) ; 


Assembly-language note: The macro you invoke to call DisposeRgn from 
assembly Language is named DisposRgn. 


DisposeRgn releases the memory occupied by the given region. Use this only after 
you're completely through with a temporary region. 


PROCEDURE CopyRgn (srcRgn,dstRgn: RgnHandle) ; 


CopyRgn copies the mathematical structure of srcRgn into dstRgn; that is, it 
makes a duplicate copy of srcRgn. Once this is done, srcRgn may be altered (or 
even disposed of) without affecting dstRgn. CopyRgn does not create the 
destination region; space must already have been allocated for it. 


PROCEDURE SetEmptyRgn (rgn: RgnHandle) ; 


SetEmptyRgn destroys the previous structure of the given region, then sets the 
new structure to the empty region defined by the rectangle (0,0)(0,0). 


PROCEDURE SetRectRgn (rgn: RgnHandle; left,top,right,bottom: INTEGER); 


Assembly-language note: The macro you invoke to call SetRectRgn from 
assembly Language is named SetRecRgn. 


SetRectRgn destroys the previous structure of the given region, and then sets 
the new structure to the rectangle specified by left, top, right, and bottom. 


If the specified rectangle is empty (that is, right<=left or bottom<=top), the 
region is set to the empty region defined by the rectangle (0,0)(0,0). 


PROCEDURE RectRgn (rgn: RgnHandle; r: Rect); 


RectRgn destroys the previous structure of the given region, and then sets the 
new structure to the rectangle specified by r. This is the same as SetRectRgn, 
except the given rectangle is defined by a rectangle rather than by four 
boundary coordinates. 


PROCEDURE OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 


Assembly-language note: The macro you invoke to call OffsetRgn from 
assembly Language is named OfsetRgn. 


OffsetRgn moves the region on the coordinate plane, a distance of dh 
horizontally and dv vertically. This doesn't affect the screen unless you 
subsequently call a routine to draw the region. If dh and dv are positive, the 
movement is to the right and down; if either is negative, the corresponding 
movement is in the opposite direction. The region retains its size and shape. 
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Note: OffsetRgn is an especially efficient operation, because most of 
the data defining a region is stored relative to rgnBBox and so 
isn't actually changed by OffsetRgn. 


PROCEDURE InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 


InsetRgn shrinks or expands the region. All points on the region boundary are 

moved inwards a distance of dv vertically and dh horizontally; if dh or dv is 

negative, the points are moved outwards in that direction. InsetRgn leaves the 
region "centered" at the same position, but moves the outline in (for positive 
values of dh and dv) or out (for negative values of dh and dv). InsetRgn of a 

rectangular region works just like InsetRect. 


Note: InsetRgn temporarily uses heap space that's twice the size of 
the original region. 


PROCEDURE SectRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle) ; 


SectRgn calculates the intersection of two regions and places the intersection 
in a third region. This does not create the destination region; space must 
already have been allocated for it. The destination region can be one of the 
source regions, if desired. 


If the regions do not intersect, or one of the regions is empty, the destination 
is set to the empty region defined by the rectangle (0,0)(0,0). 


Note: SectRgn may temporarily use heap space that's twice the size of 
the two input regions. 


PROCEDURE UnionRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle) ; 


UnionRgn calculates the union of two regions and places the union in a third 
region. This does not create the destination region; space must already have 
been allocated for it. The destination region can be one of the source regions, 
if desired. 


If both regions are empty, the destination is set to the empty region defined by 
the rectangle (0,0)(0,0). 


Note: UnionRgn may temporarily use heap space that's twice the size of 
the two input regions. 


PROCEDURE DiffRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle) ; 

DiffRgn subtracts srcRgnB from srcRgnA and places the difference in a third 
region. This does not create the destination region; space must already have 
been allocated for it. The destination region can be one of the source regions, 
if desired. 


If the first source region is empty, the destination is set to the empty region 
defined by the rectangle (0,0)(0,0). 


Note: DiffRgn may temporarily use heap space that's twice the size of 
the two input regions. 


PROCEDURE XorRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle) ; 
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XorRgn calculates the difference between the union and the intersection of 
srcRgnA and srcRgnB and places the result in dstRgn. This does not create the 
destination region; space must already have been allocated for it. The 
destination region can be one of the source regions, if desired. 


If the regions are coincident, the destination is set to the empty region 
defined by the rectangle (0,0)(0,0). 


Note: XorRgn may temporarily use heap space that's twice the size of 
the two input regions. 


FUNCTION PtInRgn (pt: Point; rgn: RgnHandle) : BOOLEAN; 


PtInRgn checks whether the pixel below and to the right of the given coordinate 
point is within the specified region, and returns TRUE if so or FALSE if not. 


FUNCTION RectInRgn (r: Rect; rgn: RgnHandle) : BOOLEAN; 


RectInRgn checks whether the given rectangle intersects the specified region, 
and returns TRUE if the intersection encloses at least one bit or FALSE if not. 


Note: RectInRgn will sometimes return TRUE when the rectangle merely 
intersects the region's enclosing rectangle. If you need to know 
exactly whether a given rectangle intersects the actual region, 
you can use RectRgn to set the rectangle to a region, and call 
SectRgn to see whether the two regions intersect: If the result 
of SectRgn is an empty region, then the rectangle doesn't intersect 
the region. 


FUNCTION EqualRgn (rgnA,rgnB: RgnHandle) : BOOLEAN; 


EqualRgn compares the two given regions and returns TRUE if they're equal or 
FALSE if not. The two regions must have identical sizes, shapes, and locations 
to be considered equal. Any two empty regions are always equal. 


FUNCTION EmptyRgn (rgn: RgnHandle) : BOOLEAN; 


EmptyRgn returns TRUE if the region is an empty region or FALSE if not. Some of 
the circumstances in which an empty region can be created are: a NewRgn call; a 
CopyRgn of an empty region; a SetRectRgn or RectRgn with an empty rectangle as 
an argument; CloseRgn without a previous OpenRgn or with no drawing after an 
OpenRgn; OffsetRgn of an empty region; InsetRgn with an empty region or too 
large an inset; SectRgn of nonintersecting regions; UnionRgn of two empty 
regions; and DiffRgn or XorRgn of two identical or nonintersecting regions. 


Graphic Operations on Regions 

These routines all depend on the coordinate system of the current grafPort. If a 
region is drawn in a different grafPort than the one in which it was defined, it 
may not appear in the proper position in the port. 


PROCEDURE FrameRgn (rgn: RgnHandle); 
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FrameRgn draws an outline just inside the specified region, using the current 
grafPort's pen pattern, mode, and size. The outline is as wide as the pen width 
and as tall as the pen height. It's drawn with the pnPat, according to the 
pattern transfer mode specified by pnMode. The outline will never go outside the 
region boundary. The pen location is not changed by this procedure. 


If a region is open and being formed, the outside outline of the region being 
framed is mathematically added to that region's boundary. 


Note: FrameRgn actually does a CopyRgn, an InsetRgn, and a DiffRgn; 
it may temporarily use heap space that's three times the size 
of the original region. 


PROCEDURE PaintRgn (rgn: RgnHandle); 

PaintRgn paints the specified region with the current grafPort's pen pattern and 
pen mode. The region is filled with the pnPat, according to the pattern transfer 
mode specified by pnMode. The pen location is not changed by this procedure. 
PROCEDURE EraseRgn (rgn: RgnHandle); 

EraseRgn paints the specified region with the current grafPort's background 
pattern bkPat (in patCopy mode). The grafPort's pnPat and pnMode are ignored; 
the pen location is not changed. 

PROCEDURE InvertRgn (rgn: RgnHandle) ; 


Assembly-language note: The macro you invoke to call InvertRgn from 
assembly Language is named InverRgn. 


InvertRgn inverts the pixels enclosed by the specified region: Every white 
pixel becomes black and every black pixel becomes white. The grafPort's pnPat, 
pnMode, and bkPat are all ignored; the pen location is not changed. 


PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 
FillRgn fills the specified region with the given pattern (in patCopy mode). The 


grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is not 
changed. 


Bit Map Operations 
PROCEDURE ScrollRect (r: Rect; dh,dv: INTEGER; updateRgn: RgnHandle) ; 


ScrollRect shifts ("Scrolls") the bits that are inside the intersection of the 
specified rectangle and the visRgn, clipRgn, portRect, and portBits.bounds of 
the current grafPort. No other bits are affected. The bits are shifted a 
distance of dh horizontally and dv vertically. The positive directions are 

to the right and down. Bits that are shifted out of the scroll area are 
lost—they're neither placed outside the area nor saved. The space created by the 
scroll is filled with the grafPort's background pattern (thePort*.bkPat), and 
the updateRgn is changed to this filled area (see Figure 23). 
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Before Afterserollbect 


Figure 23- Scrolling 
Figure 23-Scrolling 


ScrollRect doesn't change the coordinate system of the grafPort, it simply moves 
the entire document to different coordinates. Notice that ScrollRect doesn't 
move the pen and the clipRgn. However, since the document has moved, they're in 
a different position relative to the document. 


To restore the coordinates of the document to what they were before the 
ScrollRect, you can use the SetOrigin procedure. In Figure 23, suppose that 
before the ScrollRect the top left corner of the document was at coordinates 
(100,100). After ScrollRect(r,10,20...), the coordinates of the document are 
offset by the specified values. You could call SetOrigin(90,80) to offset the 
coordinate system to compensate for the scroll (see Figure 14 in the 
"Coordinates in GrafPorts" section for an illustration). The document itself 
doesn't move as a result of SetOrigin, but the pen and clipRgn move down and to 
the right, and are restored to their original position relative to the document. 
Notice that updateRgn will still need to be redrawn. 


PROCEDURE CopyBits (srcBits,dstBits: BitMap; srcRect,dstRect: Rect; 
mode: INTEGER; maskRgn: RgnHandle) ; 


CopyBits transfers a bit image between any two bit maps and clips the result to 
the area specified by the maskRgn parameter. The transfer may be performed in 
any of the eight source transfer modes. The result is always clipped to the 
maskRgn and the boundary rectangle of the destination bit map; if the 
destination bit map is the current grafPort's portBits, it's also clipped to the 
intersection of the grafPort's clipRgn and visRgn. If you don't want to clip to 
a maskRgn, just pass NIL for the maskRgn parameter. The dstRect and maskRgn 
coordinates are in terms of the dstBits.bounds coordinate system, and the 
srcRect coordinates are in terms of the srcBits.bounds coordinates. 


Warning: If you perform a CopyBits between two grafPorts that overlap, 
you must first convert to global coordinates, and then specify 
screenBits for both srcBits and dstBits. 
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The bits enclosed by the source rectangle are transferred into the destination 
rectangle according to the rules of the chosen mode. The source transfer modes 
are as follows: 


srcCopy notSrcCopy 


srcor notSrcxor 
srcxor notSrcOr 
srcBic notSrcBic 


The source rectangle is completely aligned with the destination rectangle; if 
the rectangles are of different sizes, the bit image is expanded or shrunk as 
necessary to fit the destination rectangle. For example, if the bit image is a 
circle in a square source rectangle, and the destination rectangle is not 
square, the bit image appears as an oval in the destination (see Figure 24). 


Tack 


TaskRan 
=HIL 


source hit mas eee : 
, destination hit map 


Figure 24-Operation of CopyBits 
Figure 24-Operation of CopyBits 


PROCEDURE SeedFill (srcPtr,dstPtr: Ptr; 
srcRow,dstRow,height,words,seedH,seedV: INTEGER); 


Given a source bit image, SeedFill computes a destination bit image with 1's 
only in the pixels where paint can leak from the starting seed point, like the 
MacPaint paint-bucket tool. SeedH and seedV specify horizontal and vertical 
offsets, in pixels, from the beginning of the data pointed to by dstPtr, 
determining how far into the destination bit image filling should begin. Calls 
to SeedFill are not clipped to the current port and are not stored into 
QuickDraw pictures. 


PROCEDURE CalcMask (srcPtr,dstPtr: Ptr; srcRow,dstRow,height, words: INTEGER); 
Given a source bit image, CalcMask computes a destination bit image with 1's 


only in the pixels where paint could not leak from any of the outer edges, like 
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the MacPaint lasso tool. Calls to CalcMask are not clipped to the current port 
and are not stored into QuickDraw pictures. 


PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; 
srcRect, maskRect,dstRect: Rect); 


CopyMask is a new version of the CopyBits procedure; it transfers a bit image 
from the source bitmap to the destination bitmap only where the corresponding 
bit of the mask rectangle is a 1. (Note that the mask is specified as a 
rectangle instead of as a handle to a region.) It can be used along with 
CalcMask to implement the lasso copy as in MacPaint; it's also useful for 
drawing icons. CopyMask doesn't check for overlap between the source and 
destination bitmaps, doesn't stretch the bit image, and doesn't store into 
QuickDraw pictures. CopyMask does, however, respect the current port's visRgn 
and clipRgn if dstBits is the portBits of the current grafPort. 


Pictures 
FUNCTION OpenPicture (picFrame: Rect) : PicHandle; 


OpenPicture returns a handle to a new picture that has the given rectangle as 
its picture frame, and tells QuickDraw to start saving as the picture definition 
all calls to drawing routines and all picture comments (if any). 


OpenPicture calls HidePen, so no drawing occurs on the screen while the picture 
is open (unless you call ShowPen just after OpenPicture, or you called ShowPen 
previously without balancing it by a call to HidePen). 


When a picture is open, the current grafPort's picSave field contains a handle 
to information related to the picture definition. If you want to temporarily 
disable the collection of routine calls and picture comments, you can save the 
current value of this field, set the field to NIL, and later restore the saved 
value to resume the picture definition. 


Warning: Do not call OpenPicture while another picture is already open. 


Warning: A grafPort's clipRgn is initialized to an arbitrarily large 
region. You should always change the clipRgn to a smaller 
region before calling OpenPicture, or no drawing may occur 
when you call DrawPicture. 


PROCEDURE ClosePicture; 


ClosePicture tells QuickDraw to stop saving routine calls and picture comments 
as the definition of the currently open picture. You should perform one and only 
one ClosePicture for every OpenPicture. ClosePicture calls ShowPen, balancing 
the HidePen call made by OpenPicture. 


PROCEDURE PicComment (kind,dataSize: INTEGER; dataHandle: Handle); 


PicComment inserts the specified comment into the definition of the currently 
open picture. The kind parameter identifies the type of comment. DataHandle is a 
handle to additional data if desired, and dataSize is the size of that data in 
bytes. If there's no additional data for the comment, dataHandle should be NIL 
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and dataSize should be 0. An application that processes the comments must 
include a procedure to do the processing and store a pointer to it in the data 
structure pointed to by the grafProcs field of the grafPort (see "Customizing 
QuickDraw Operations"). 


Note: The standard low-level procedure for processing picture comments 
Simply ignores all comments. 


PROCEDURE DrawPicture (myPicture: PicHandle; dstRect: Rect); 


DrawPicture takes the part of the given picture that's inside the picture frame 
and draws it in dstRect, expanding or shrinking it as necessary to align the 
borders of the picture frame with dstRect. DrawPicture passes any picture 
comments to a low-level procedure accessed indirectly through the grafProcs 
field of the grafPort (see PicComment above). 


Warning: If you call DrawPicture with the initial, arbitrarily large 
clipRgn and the destination rectangle is offset from the 
picture frame, you may end up with an empty clipRgn, and no 
drawing will take place. 


PROCEDURE KillPicture (myPicture: PicHandle); 
KillPicture releases the memory occupied by the given picture. Use this only 


when you're completely through with a picture (unless the picture is a resource, 
in which case use the Resource Manager procedure ReleaseResource). 


Calculations with Polygons 
FUNCTION OpenPoly : PolyHandle; 


OpenPoly returns a handle to a new polygon and tells QuickDraw to start saving 
the polygon definition as specified by calls to line-drawing routines. While a 
polygon is open, all calls to Line and LineTo affect the outline of the polygon. 
Only the line endpoints affect the polygon definition; the pen mode, pattern, 
and size do not affect it. In fact, OpenPoly calls HidePen, so no drawing occurs 
on the screen while the polygon is open (unless you call ShowPen just after 
OpenPoly, or you called ShowPen previously without balancing it by a call to 
HidePen) . 


A polygon should consist of a sequence of connected lines. Even though the on- 
screen presentation of a polygon is clipped, the definition of a polygon is not; 
you can define a polygon anywhere on the coordinate plane. 


When a polygon is open, the current grafPort's polySave field contains a handle 
to information related to the polygon definition. If you want to temporarily 
disable the polygon definition, you can save the current value of this field, 
set the field to NIL, and later restore the saved value to resume the polygon 
definition. 


Warning: Do not call OpenPoly while a region or another polygon is 
already open. 


Note: Polygons are limited to 32K bytes; you can determine the polygon 
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size while it's being formed by calling the Memory Manager function 
GetHandleSize. 


PROCEDURE ClosePoly; 


Assembly-language note: The macro you invoke to call ClosePoly from 
assembly Language is named ClosePgon. 


ClosePoly tells QuickDraw to stop saving the definition of the currently open 
polygon and computes the polyBBox rectangle. You should perform one and only one 
ClosePoly for every OpenPoly. ClosePoly calls ShowPen, balancing the HidePen 
call made by OpenPoly. 


Here's an example of how to open a polygon, define it as a triangle, close it, 
and draw it: 


triPoly := OpenPoly; {save handle and begin collecting stuff} 
MoveTo(300,100) ; {move to first point and } 
LineTo(400, 200) ; { form } 
LineTo(200, 200) ; { the } 
LineTo(300,100) ; { triangle } 
ClosePoly; {stop collecting stuff} 
FillPoly(triPoly,gray); {draw it on the screen} 
KillPoly(triPoly) {we're all done} 


PROCEDURE KillPoly (poly: PolyHandle) ; 


KillPoly releases the memory occupied by the given polygon. Use this only when 
you're completely through with a polygon. 


PROCEDURE OffsetPoly (poly: PolyHandle; dh,dv: INTEGER); 


OffsetPoly moves the polygon on the coordinate plane, a distance of dh 
horizontally and dv vertically. This doesn't affect the screen unless you 
subsequently call a routine to draw the polygon. If dh and dv are positive, the 
movement is to the right and down; if either is negative, the corresponding 
movement is in the opposite direction. The polygon retains its shape and size. 


Note: OffsetPoly is an especially efficient operation, because the data 
defining a polygon is stored relative to the first point of the 
polygon and so isn't actually changed by OffsetPoly. 


Graphic Operations on Polygons 


Four of the operations described here—PaintPoly, ErasePoly, InvertPoly, and 
FillPoly—temporarily convert the polygon into a region to perform their 
operations. The amount of memory required for this temporary region may be far 
greater than the amount required by the polygon alone. You can estimate the size 
of this region by scaling down the polygon with MapPoly, converting it into a 
region, checking the region's size with the Memory Manager function 
GetHandleSize, and multiplying that value by the factor by which you scaled down 
the polygon. 


Warning: If any horizontal or vertical line drawn through the polygon 
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would intersect the polygon's outline more than 50 times, the 
results of these graphic operations are undefined. 


PROCEDURE FramePoly (poly: PolyHandle) ; 


FramePoly plays back the line-drawing routine calls that define the given 
polygon, using the current grafPort's pen pattern, mode, and size. The pen will 
hang below and to the right of each point on the boundary of the polygon; 

thus, the polygon drawn will extend beyond the right and bottom edges of 
poly**.polyBBox by the pen width and pen height, respectively. All other graphic 
operations occur strictly within the boundary of the polygon, as for other 
shapes. You can see this difference in Figure 25, where each of the polygons is 
shown with its polyBBox. 


FrameFoly FaintFoly 


Figure 25-Drawing Polygons 

Figure 25—Drawing Polygons 
If a polygon is open and being formed, FramePoly affects the outline of the 
polygon just as if the line-drawing routines themselves had been called. If a 


region is open and being formed, the outside outline of the polygon being framed 
is mathematically added to the region's boundary. 


PROCEDURE PaintPoly (poly: PolyHandle) ; 

PaintPoly paints the specified polygon with the current grafPort's pen pattern 
and pen mode. The polygon is filled with the pnPat, according to the pattern 
transfer mode specified by pnMode. The pen location is not changed by this 
procedure. 

PROCEDURE ErasePoly (poly: PolyHandle) ; 

ErasePoly paints the specified polygon with the current grafPort's background 
pattern bkPat (in patCopy mode). The pnPat and pnMode are ignored; the pen 
location is not changed. 


PROCEDURE InvertPoly (poly: PolyHandle) ; 
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InvertPoly inverts the pixels enclosed by the specified polygon: Every white 
pixel becomes black and every black pixel becomes white. The grafPort's pnPat, 
pnMode, and bkPat are all ignored; the pen location is not changed. 


PROCEDURE FillPoly (poly: PolyHandle; pat: Pattern); 
FillPoly fills the specified polygon with the given pattern (in patCopy mode). 


The grafPort's pnPat, pnMode, and bkPat are all ignored; the pen location is not 
changed. 


Calculations with Points 
PROCEDURE AddPt (srcPt: Point; VAR dstPt: Point); 


AddPt adds the coordinates of srcPt to the coordinates of dstPt, and returns the 
result in dstPt. 


PROCEDURE SubPt (srcPt: Point; VAR dstPt: Point); 


SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, and 
returns the result in dstPt. 


Note: To get the results of coordinate subtraction returned as a function 
result, you can use the Toolbox Utility function DeltaPoint. 


PROCEDURE SetPt (VAR pt: Point; h,v: INTEGER); 
SetPt assigns the two given coordinates to the point pt. 
FUNCTION EqualPt (pt1,pt2: Point) : BOOLEAN; 


EqualPt compares the two given points and returns TRUE if they're equal or FALSE 
if not. 


PROCEDURE LocalToGlobal (VAR pt: Point); 


LocalToGlobal converts the given point from the current grafPort's local 
coordinate system into a global coordinate system with the origin (0,0) at the 
top left corner of the port's bit image (such as the screen). This global point 
can then be compared to other global points, or be changed into the local 
coordinates of another grafPort. 


Since a rectangle is defined by two points, you can convert a rectangle into 
global coordinates by performing two LocalToGlobal calls. You can also convert a 
rectangle, region, or polygon into global coordinates by calling OffsetRect, 
OffsetRgn, or OffsetPoly. For examples, see GlobalToLocal below. 


PROCEDURE GlobalToLocal (VAR pt: Point); 


GlobalToLocal takes a point expressed in global coordinates (with the top left 
corner of the bit image as coordinate (0,0)) and converts it into the local 
coordinates of the current grafPort. The global point can be obtained with the 
LocalToGlobal call (see above). For example, suppose a game draws a "ball" 
within a rectangle named ballRect, defined in the grafPort named gamePort (as 
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illustrated in Figure 26). If you want to draw that ball in the grafPort named 
selectPort, you can calculate the ball's selectPort coordinates like this: 


SetPort(gamePort) ; {start in origin port} 
selectBall := ballRect; {make a copy to be moved} 
LocalToGlobal(selectBall.topLeft) ; {put both corners into } 
LocalToGlobal(selectBall.botRight) ; { global coordinates} 
SetPort(selectPort) ; {switch to destination port} 
GlobalToLocal(selectBall.topLeft) ; {put both corners into } 
GlobalToLocal(selectBall.botRight) ; { these local coordinates} 
FillOval(selectBall,ballColor) {draw the ball} 


selectF ort 


GlobalToLocal 


Figure 26-Conyerting between Coorinate Systems 
Figure 26—Converting between Coordinate Systems 


You can see from Figure 26 that LocalToGlobal and GlobalToLocal simply offset 
the coordinates of the rectangle by the coordinates of the top left corner of 
the local grafPort's portBits.bounds rectangle. You could also do this with 
OffsetRect. In fact, the way to convert regions and polygons from one coordinate 
system to another is with OffsetRgn or OffsetPoly rather than LocalToGlobal and 
GlobalToLocal. For example, if myRgn were a region enclosed by a rectangle 
having the same coordinates as ballRect in gamePort, you could convert the 
region to global coordinates with 


OffsetRgn(myRgn, -20, -40) 
and then convert it to the coordinates of the selectPort grafPort with 


OffsetRgn(myRgn, 15, -30) 


Miscellaneous Routines 
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FUNCTION Random : INTEGER; 


This function returns a pseudo-random integer, uniformly distributed in the 
range —32767 through 32767. The value the sequence starts from depends on the 
global variable randSeed, which InitGraf initializes to 1. To start the sequence 
over again from where it began, reset randSeed to 1. To start a new sequence 
each time, you must reset randSeed to a random number. 


Note: You can start a new sequence by storing the current date and time 
in randSeed; see GetDateTime in the Operating System Utilities chapter. 


Assembly-language note: From assembly language, it's better to start a new 
sequence by storing the value of the system global 
variable RndSeed in randSeed. 


FUNCTION GetPixel (h,v: INTEGER) : BOOLEAN; 


GetPixel looks at the pixel associated with the given coordinate point and 
returns TRUE if it's black or FALSE if it's white. The selected pixel is 
immediately below and to the right of the point whose coordinates are given in h 
and v, in the local coordinates of the current grafPort. There's no guarantee 
that the specified pixel actually belongs to the port, however; it may have been 
drawn by a port overlapping the current one. To see if the point indeed belongs 
to the current port, you could call PtInRgn(pt, thePort*.visRgn). 


Note: To find out which window's grafPort a point lies in, you call the 
Window Manager function FindWindow, as described in the Window 
Manager chapter. 


PROCEDURE StuffHex (thingPtr: Ptr; s: Str255); 


StuffHex stores bits (expressed as a string of hexadecimal digits) into any data 
structure. You can easily create a pattern in your program with Stuf fHex 
(though more likely, you'll store patterns in a resource file). For example, 


Stuf fHex(@stripes, '0102040810204080' ) 
places a striped pattern into the pattern variable named stripes. 


Warning: There's no range checking on the size of the destination variable. 
It's easy to overrun the variable and destroy something if you 
don't know what you're doing. 


PROCEDURE ScalePt (VAR pt: Point; srcRect,dstRect: Rect); 


A width and height are passed in pt; the horizontal component of pt is the 
width, and its vertical component is the height. ScalePt scales these 
measurements as follows and returns the result in pt: It multiplies the given 
width by the ratio of dstRect's width to srcRect's width, and multiplies the 
given height by the ratio of dstRect's height to srcRect's height. 


ScalePt can be used, for example, for scaling the pen dimensions. In Figure 27, 
where dstRect's width is twice srcRect's width and its height is three times 
srcRect's height, the pen width is scaled from 3 to 6 and the pen height is 
scaled from 2 to 6. 
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Note: The minimum value ScalePt will return is (1,1). 


| I sre Rect i ‘i 


BealePt sealer peu size (3,2) to (6,6) 
MapPt maps size [3,2] to (18,7) 


Figure 27-ScalePt and MapPt 
Figure 27-ScalePt and MapPt 


PROCEDURE MapPt (VAR pt: Point; srcRect,dstRect: Rect); 


Given a point within srcRect, MapPt maps it to a similarly located point within 
dstRect (that is, to where it would fall if it were part of a drawing being 
expanded or shrunk to fit dstRect). The result is returned in pt. A corner point 
of srcRect would be mapped to the corresponding corner point of dstRect, and the 
center of srcRect to the center of dstRect. In Figure 27, the point 

(3,2) in srcRect is mapped to (18,7) in dstRect. SrcRect and dstRect may 
overlap, and pt need not actually be within srcRect. 


Note: Remember, if you're going to draw inside the destination rectangle, 
you'll probably also want to scale the pen size accordingly with ScalePt. 


PROCEDURE MapRect (VAR r: Rect; srcRect,dstRect: Rect); 


Given a rectangle within srcRect, MapRect maps it to a similarly located 
rectangle within dstRect by calling MapPt to map the top left and bottom right 
corners of the rectangle. The result is returned in r. 


PROCEDURE MapRgn (rgn: RgnHandle; srcRect,dstRect: Rect); 


Given a region within srcRect, MapRgn maps it to a similarly located region 
within dstRect by calling MapPt to map all the points in the region. 


Note: MapRgn is useful for determining whether a region operation will 
exceed available memory: By mapping a large region into a smaller 
one and performing the operation (without actually drawing), you 
can estimate how much memory will be required by the anticipated 
operation. 
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PROCEDURE MapPoly (poly: PolyHandle; srcRect,dstRect: Rect); 


Given a polygon within srcRect, MapPoly maps it to a similarly located polygon 
within dstRect by calling MapPt to map all the points that define the polygon. 


Note: Like MapRgn, MapPoly is useful for determining whether a polygon 
operation will succeed. 


Advanced Routine 


The function GetMaskTable, accessible only from assembly language, returns in 
register AO a pointer to a ROM table containing the following useful masks: 


.WORD $0000, $8000,$C000,$EQ00  ;Table of 16 right masks 
.WORD $F000, $F800,$FCOO, $FEOO 
.WORD $FF0O, $FF80,$FFCO, $FFEO 
.WORD $FFFO, $FFF8,$FFFC, $FFFE 


.WORD $FFFF,$7FFF,$3FFF,$1FFF ;Table of 16 left masks 
.WORD $OFFF,$07FF,$03FF,$01FF 
.WORD $00FF,$007F,$003F,$001F 
.WORD $000F, $0007, $0003, $0001 


.WORD $8000, $4000, $2000, $1000 ‘Table of 16 bit masks 
.WORD $0800, $0400, $0200, $0100 
.WORD $0080, $0040, $0020, $0010 
.WORD $0008, $0004, $0002 ,$0001 
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CUSTOMIZING QUICKDRAW OPERATIONS 


For each shape that QuickDraw knows how to draw, there are procedures that 
perform these basic graphic operations on the shape: frame, paint, erase, 
invert, and fill. Those procedures in turn call a low-level drawing routine for 
the shape. For example, the FrameOval, PaintOval, EraseOval, InvertOval, and 
FillOval procedures all call a low-level routine that draws the oval. For each 
type of object QuickDraw can draw, including text and lines, there's a pointer 
to such a routine. By changing these pointers, you can install your own 
routines, and either completely override the standard ones or call them after 
your routines have modified parameters as necessary. 


Other low-level routines that you can install in this way are: 


¢ The procedure that does bit transfer and is called by CopyBits. 

¢ The function that measures the width of text and is called by 
CharWidth, StringWidth, and TextWidth. 

« The procedure that processes picture comments and is called by 
DrawPicture. The standard such procedure ignores picture comments. 

« The procedure that saves drawing commands as the definition of a 
picture, and the one that retrieves them. This enables the application 
to draw on remote devices, print to the disk, get picture input from 
the disk, and support large pictures. 


The grafProcs field of a grafPort determines which low-level routines are 
called; if it contains NIL, the standard routines are called, so that all 
operations in that grafPort are done in the standard ways described in this 
chapter. You can set the grafProcs field to point to a record of pointers to 
routines. The data type of grafProcs is QDProcsPtr: 


TYPE QDProcsPtr = “QDProcs; 
QDProcs = RECORD 
textProc: Ptr; {text drawing} 
lineProc: Ptr; {line drawing} 
rectProc: Ptr; {rectangle drawing} 
rRectProc: Ptr; {roundRect drawing} 
ovalProc: Ptr; {oval drawing} 
arcProc: Ptr; {arc/wedge drawing} 
polyProc: Ptr; {polygon drawing} 
rgnProc: Ptr; {region drawing} 
bitsProc: Ptr; {bit transfer} 
commentProc: Ptr; {picture comment processing} 
txMeasProc: Ptr; {text width measurement} 
getPicProc: Ptr; {picture retrieval} 
putPicProc: Ptr {picture saving} 
END; 


To assist you in setting up a QDProcs record, QuickDraw provides the following 
procedure: 


PROCEDURE SetStdProcs (VAR procs: QDProcs); 
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This procedure sets all the fields of the given QDProcs record to point to the 
standard low-level routines. You can then change the ones you wish to point to 
your own routines. For example, if your procedure that processes picture 
comments is named MyComments, you'll store @MyComments in the commentProc field 
of the QDProcs record. 


You can either write your own routines to completely replace the standard ones, 
or do preprocessing and then call the standard routines. The routines you 
install must of course have the same calling sequences as the standard routines, 
which are described below. 


Note: These low-level routines should be called only from your 
customized routines. 


The standard drawing routines tell which graphic operation to perform from a 
parameter of type GrafVerb: 


TYPE GrafVerb = (frame,paint,erase,invert, fill); 


When the grafVerb is fill, the pattern to use during filling is passed in the 
fillPat field of the grafPort. 


PROCEDURE StdText (byteCount: INTEGER; textBuf: Ptr; numer,denom: Point); 


StdText is the standard low-level routine for drawing text. It draws text from 
the arbitrary structure in memory specified by textBuf, starting from the first 
byte and continuing for byteCount bytes. Numer and denom specify the scaling 
factor: mnumer.v over denom.v gives the vertical scaling, and numer.h over 
denom.h gives the horizontal scaling. 


PROCEDURE StdLine (newPt: Point); 

StdLine is the standard low-level routine for drawing a line. It draws a line 
from the current pen location to the location specified (in local coordinates) 
by newPt. 

PROCEDURE StdRect (verb: GrafVerb; r: Rect); 


StdRect is the standard low-level routine for drawing a rectangle. It draws the 
given rectangle according to the specified grafVerb. 


PROCEDURE StdRRect (verb: GrafVerb; r: Rect; ovalwidth, ovalHeight: INTEGER) 
StdRRect is the standard low-level routine for drawing a rounded-corner 
rectangle. It draws the given rounded-corner rectangle according to the 
specified grafVerb. OvalWidth and ovalHeight specify the diameters of curvature 
for the corners. 

PROCEDURE StdOval (verb: GrafVerb; r: Rect); 


StdOval is the standard low-level routine for drawing an oval. It draws an oval 
inside the given rectangle according to the specified grafVerb. 


PROCEDURE StdArc (verb: GrafVerb; r: Rect; startAngle,arcAngle: INTEGER); 
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StdArc is the standard low-level routine for drawing an arc or a wedge. It draws 
an arc or wedge of the oval that fits inside the given rectangle, beginning at 
startAngle and extending to arcAngle. The grafVerb specifies the graphic 
operation; if it's the frame operation, an arc is drawn; otherwise, a wedge is 
drawn. 


PROCEDURE StdPoly (verb: GrafVerb; poly: PolyHandle); 


StdPoly is the standard low-level routine for drawing a polygon. It draws the 
given polygon according to the specified grafVerb. 


PROCEDURE StdRgn (verb: GrafVerb; rgn: RgnHandle); 


StdRgn is the standard low-level routine for drawing a region. It draws the 
given region according to the specified grafVerb. 


PROCEDURE StdBits (VAR srcBits: BitMap; VAR srcRect,dstRect: Rect; 
mode: INTEGER; maskRgn: RgnHandle) ; 


StdBits is the standard low-level routine for doing bit transfer. It transfers a 
bit image between the given bit map and thePort*.portBits, just as if CopyBits 
were called with the same parameters and with a destination bit map equal to 
thePort*.portBits. 


PROCEDURE StdComment (kind,dataSize: INTEGER; dataHandle: Handle); 


StdComment is the standard low-level routine for processing a picture comment. 
The kind parameter identifies the type of comment. DataHandle is a handle to 
additional data, and dataSize is the size of that data in bytes. If there's no 
additional data for the comment, dataHandle will be NIL and dataSize will be 0. 
StdComment simply ignores the comment. 


FUNCTION StdTxMeas (byteCount: INTEGER; textAddr: Ptr; 
VAR numer, denom: Point; VAR info: FontInfo) : INTEGER; 


StdTxMeas is the standard low-level routine for measuring text width. It returns 
the width of the text stored in the arbitrary structure in memory specified by 
textAddr, starting with the first byte and continuing for byteCount bytes. Numer 
and denom specify the scaling as in the StdText procedure; note that StdTxMeas 
may change them. 


PROCEDURE StdGetPic (dataPtr: Ptr; byteCount: INTEGER); 


StdGetPic is the standard low-level routine for retrieving information from the 
definition of a picture. It retrieves the next byteCount bytes from the 
definition of the currently open picture and stores them in the data structure 
pointed to by dataPtr. 


PROCEDURE StdPutPic (dataPtr: Ptr; byteCount: INTEGER); 


StdPutPic is the standard low-level routine for saving information as the 
definition of a picture. It saves as the definition of the currently open 
picture the drawing commands stored in the data structure pointed to by dataPtr, 
starting with the first byte and continuing for the next byteCount bytes. 
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SUMMARY OF QUICKDRAW 


Constants 
CONST 
{ Source transfer modes } 


srcCopy 
srcor 
srcxor 
srcBic 
notSrcCopy 
notSrcOr 
notSrcxor 
notSrcBic 


NOUBWNEF © 


{ Pattern transfer modes } 


patCopy = 8; 
patOr = 9; 
patXor = 10; 
patBic = 11; 
notPatCopy = 12; 
notPatOr = 13; 
notPatXor = 14; 
notPatBic = 15; 


{ Standard colors for ForeColor and BackColor } 


blackColor = 33; 
whiteColor = 30; 
redColor = 209; 
greenColor = 329; 
blueColor = 389; 
cyanColor = 269; 
magentaColor = 149; 
yellowColor = 89; 


{ Standard picture comments } 


picLParen = 0; 
picRParen = 1; 
Data Types 
TYPE 
StyleItem = (bold,italic,underline, outline, shadow, condense, extend) ; 
Style = SET OF StyleItem; 
VHSelect = (v,h); 
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Point = RECORD CASE INTEGER OF 


O: (v: INTEGER; {vertical coordinate} 
h: INTEGER); {horizontal coordinate} 
1: (vh: ARRAY[VHSelect] OF INTEGER) 
END; 
Rect = RECORD CASE INTEGER OF 
0: (top: INTEGER; 
left: INTEGER; 


bottom: INTEGER; 
right: INTEGER) ; 
1: (topLeft: Point; 
botRight: Point) 


END; 
RgnHandle = “RgnPtr; 
RgnPtr = “Region; 
Region = RECORD 
rgnSize: INTEGER; {size in bytes} 
rgnBBox: Rect; {enclosing rectangle} 
{more data if not rectangular} 
END; 
BitMap = RECORD 
baseAddr: Ptr; {pointer to bit image} 
rowBytes: INTEGER; {row width} 
bounds: Rect {boundary rectangle} 
END; 


Pattern = PACKED ARRAY[0..7] OF 0..255; 


Bits16 = ARRAY[0..15] OF INTEGER; 
Cursor = RECORD 
data: Bits16; {cursor image} 
mask: Bits16; {cursor mask} 
hotSpot: Point {point aligned with mouse} 
END; 
QDProcsPtr = *“QDProcs; 
QDProcs = RECORD 
textProc: Ptr; {text drawing} 
LlineProc: Ptr; {line drawing} 
rectProc: Ptr; {rectangle drawing} 
rRectProc: Ptr; {roundRect drawing} 
ovalProc: Ptr; {oval drawing} 
arcProc: Ptr; {arc/wedge drawing} 
rgnProc: Ptr; {region drawing} 
bitsProc: Ptr; {bit transfer} 
commentProc: Ptr; {picture comment processing} 
txMeasProc: Ptr; {text width measurement} 
getPicProc: Ptr; {picture retrieval} 
putPicProc: Ptr {picture saving} 
END; 


GrafPtr = *GrafPort; 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
QUICKDRAW ¢ 76 of 86 


GrafPort = RECORD 
device: 
portBits: 
portRect: 
visRgn: 
clipRgn: 
bkPat: 
fillPat: 
pnLoc: 
pnSize: 
pnMode: 
pnPat: 
pnVis: 
txFont: 
txFace: 
txMode: 
txSize: 
spExtra: 
fgColor: 
bkColor: 
colrBit: 
patStretc 
picSave: 
rgnSave: 
polySave: 


grafProcs: 


END; 


PicHandle 
PicPtr 
Picture 


“PicPtr; 

“Picture; 

RECORD 
picSize: 


picFrame: 


INTEGER; {device-specific information} 
BitMap; {grafPort's bit map} 
Rect; {grafPort's rectangle} 
RgnHandle; {visible region} 
RgnHandle; {clipping region} 
Pattern; {background pattern} 
Pattern; {fill pattern} 

Point; {pen Location} 

Point; {pen size} 

INTEGER; {pen's transfer mode} 
Pattern; {pen pattern} 

INTEGER; {pen visibility} 
INTEGER; {font number for text} 
Style; {text's character style} 
INTEGER; {text's transfer mode} 
INTEGER; {font size for text} 
Fixed; {extra space} 

LONGINT; {foreground color} 
LONGINT; {background color} 
INTEGER; {color bit} 

h: INTEGER; {used internally} 
Handle; {picture being saved} 
Handle; {region being saved} 
Handle; {polygon being saved} 
QDProcsPtr {low-level drawing routines} 

INTEGER; {size in bytes} 
Rect; {picture frame} 


{picture definition data} 


END; 


PolyHandle 
PolyPtr 
Polygon 


“PolyPtr; 
“Polygon; 
RECORD 
polySiz 
polyBBo 
polyPoi 
END; 


RECORD 
pnLoc: 
pnSize: 
pnMode: 
pnPat: 

END; 


PenState 


RECORD 
ascent: 
descent: 
widMax: 
leading: 


FontiInfo 


@ SpiInside 


e: INTEGER; {size in bytes} 
x! Rect; {enclosing rectangle} 
nts: ARRAY[Q..0] OF Point 
Point; {pen location} 
Point; {pen size} 
INTEGER; {pen's transfer mode} 
Pattern {pen pattern} 
INTEGER; {ascent} 
INTEGER; {descent} 
INTEGER; {maximum character width} 
INTEGER {leading} 
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END; 


GrafVerb = (frame,paint,erase,invert, fill); 
Variables 
VAR 

thePort: GrafPtr; {pointer to current grafPort} 

white: Pattern; {all-white pattern} 

black: Pattern; {all-black pattern} 

gray: Pattern; {50% gray pattern} 

LtGray: Pattern; {25% gray pattern} 

dkGray: Pattern; {75% gray pattern} 

arrow: Cursor; {standard arrow cursor} 

screenBits: BitMap; {the entire screen} 

randSeed: LONGINT; {determines where Random sequence begins} 
Routines 


GrafPort Routines 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


Cursor Han 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


PROCEDURE ObscureCursor; 


Pen and Li 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


InitGraf (globalPtr: Ptr); 
OpenPort (port: GrafPtr); 
InitPort (port: GrafPtr); 
ClosePort (port: GrafPtr); 

SetPort (port: GrafPtr); 

GetPort (VAR port:GrafPtr) ; 
GrafDevice (device: INTEGER) ; 
SetPortBits (bm BitMap) ; 

PortSize iwidth, height: INTEGER); 
MovePortTo ot ee: topGlobal: INTEGER); 
SetOrigin (h INTEGER) ; 

SetClip (ran. RgnHandle) ; 
GetClip (rgn: RgnHandle) ; 
ClipRect (r Rect); 

BackPat (pat: Pattern); 

dling 

InitCursor; 

SetCursor (crsr: Cursor); 
HideCursor; 

ShowCursor; 

ne Drawing 

HidePen; 

ShowPen; 

GetPen (VAR pt: Point); 
GetPenState (VAR pnState: PenState); 
SetPenState (pnState: PenState); 
PenSize (width,height: INTEGER); 
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PROCEDURE PenMode (mode: INTEGER); 
PROCEDURE PenPat (pat: Pattern); 
PROCEDURE PenNormal; 
PROCEDURE MoveTo (h,v: INTEGER); 
PROCEDURE Move (dh,dv INTEGER) ; 
PROCEDURE LineTo (h,v: INTEGER); 
PROCEDURE Line (dh, dv INTEGER) ; 
Text Drawing 
PROCEDURE TextFont (font INTEGER) ; 
PROCEDURE TextFace (face: Style); 
PROCEDURE TextMode (mode INTEGER) ; 
PROCEDURE TextSize (size INTEGER) ; 
PROCEDURE SpaceExtra (extra Fixed); 
PROCEDURE DrawChar (ch: CHAR); 
PROCEDURE DrawString (s: Str255); 
PROCEDURE DrawText (textBuf Ptr; firstByte,byteCount: INTEGER); 
FUNCTION CharWidth (ch: CHAR) INTEGER; 
FUNCTION StringWidth (s: Str255) INTEGER; 
FUNCTION TextWidth (textBuf: Ptr; 
firstByte,byteCount: INTEGER) INTEGER; 
PROCEDURE MeasureText (count: INTEGER; textAddr,charLocs: Ptr); 
PROCEDURE GetFontInfo (VAR info: FontInfo); 
Drawing in Color 
PROCEDURE ForeColor (color: LONGINT); 
PROCEDURE BackColor (color: LONGINT); 
PROCEDURE ColorBit (whichBit: INTEGER); 
Calculations with Rectangles 
PROCEDURE SetRect (VAR r: Rect; left,top,right,bottom: INTEGER); 
PROCEDURE OffsetRect (VAR r: Rect; dh,dv: INTEGER); 
PROCEDURE InsetRect (VAR r: Rect; dh,dv: INTEGER); 
FUNCTION SectRect (srcl,src2: Rect; VAR dstRect: Rect) BOOLEAN; 
PROCEDURE UnionRect oe src2: Rect; VAR dstRect: Rect); 
FUNCTION PtInRect (pt Point; r: Rect) BOOLEAN; 
PROCEDURE Pt2Rect (pt, pt2: Point; VAR dstRect: Rect); 
PROCEDURE PtToAngle (r Rect; pt: Point; VAR angle: INTEGER); 
FUNCTION EqualRect (rect, rect2: Rect) BOOLEAN; 
FUNCTION EmptyRect (r: Rect) BOOLEAN; 
Graphic Operations on Rectangles 
PROCEDURE FrameRect (r Rect); 
PROCEDURE PaintRect (r Rect); 
PROCEDURE EraseRect (r Rect); 
PROCEDURE InvertRect (r Rect); 
PROCEDURE FillRect (r Rect; pat: Pattern); 


Graphic Operations on Ovals 


PROCEDURE FrameOval (r: 
PROCEDURE PaintOval (r: 


Rect); 
Rect); 
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PROCEDURE EraseOval (r: Rect); 
PROCEDURE InvertOval (r: Rect); 
PROCEDURE Fill0val (r: Rect; pat: Pattern); 


Graphic Operations on Rounded-Corner Rectangles 


PROCEDURE FrameRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 

PROCEDURE PaintRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 

PROCEDURE EraseRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 

PROCEDURE InvertRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER); 

PROCEDURE FillLRoundRect (r: Rect; ovalWidth,ovalHeight: INTEGER; 

pat: Pattern); 

Graphic Operations on Arcs and Wedges 

PROCEDURE FrameArc (r Rect; startAngle,arcAngle: INTEGER); 

PROCEDURE PaintArc (r: Rect; startAngle,arcAngle: INTEGER); 

PROCEDURE EraseArc (r: Rect; startAngle,arcAngle: INTEGER); 

PROCEDURE InvertArc (r: Rect; startAngle,arcAngle: INTEGER); 

PROCEDURE FillArc (r Rect; startAngle,arcAngle: INTEGER; pat: Pattern); 

Calculations with Regions 

FUNCTION NewRgn : RgnHandle; 

PROCEDURE OpenRgn; 

PROCEDURE CloseRgn (dstRgn: RgnHandle); 

PROCEDURE DisposeRgn (rgn: RgnHandle); 

PROCEDURE CopyRgn (srcRgn,dstRgn: RgnHandle); 

PROCEDURE SetEmptyRgn (rgn: RgnHandle) ; 

PROCEDURE SetRectRgn (rgn: RgnHandle; left,top,right,bottom: INTEGER); 

PROCEDURE RectRgn (rgn RgnHandle; r: Rect); 

PROCEDURE OffsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 

PROCEDURE InsetRgn (rgn: RgnHandle; dh,dv: INTEGER); 

PROCEDURE SectRgn (srcRgnA,srcRgnB, dstRgn: RgnHandle) ; 

PROCEDURE UnionRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

PROCEDURE DiffRgn (srcRgnA,srcRgnB,dstRgn: RgnHandle); 

PROCEDURE XorRgn ps srcRgnB,dstRgn: RgnHandle) ; 

FUNCTION PtInRgn (pt Point; rgn: RgnHandle) BOOLEAN; 

FUNCTION RectInRgn (r: Rect; rgn: RgnHandle) BOOLEAN; 

FUNCTION EqualRgn rand, rgnB: RgnHandle) BOOLEAN; 

FUNCTION EmptyRgn (rgn: RgnHandle) BOOLEAN; 

Graphic Operations on Regions 

PROCEDURE FrameRgn (rgn: RgnHandle); 

PROCEDURE PaintRgn (rgn: RgnHandle); 

PROCEDURE EraseRgn (rgn: RgnHandle); 

PROCEDURE InvertRgn (rgn: RgnHandle) ; 

PROCEDURE FillRgn (rgn: RgnHandle; pat: Pattern); 

Bit Map Operations 

PROCEDURE ScrollRect (r: Rect; dh,dv: INTEGER; updateRgn: RgnHandle) ; 

PROCEDURE CopyBits (srcBits,dstBits: BitMap; srcRect,dstRect: Rect; 
mode: INTEGER; maskRgn: RgnHandle) ; 

PROCEDURE SeedFill (srcPtr,dstPtr: Ptr; 
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srcRow,dstRow,height,words, seedH,seedV: INTEGER); 


PROCEDURE CalcMask (srcPtr,dstPtr: Ptr; 
srcRow,dstRow,height,words: INTEGER); 

PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; 
srcRect, maskRect,dstRect: ect); 


Pictures 


FUNCTION OpenPicture (picFrame: Rect) : PicHandle; 

PROCEDURE PicComment (kind,dataSize: INTEGER; dataHandle: Handle); 
PROCEDURE ClosePicture; 

PROCEDURE DrawPicture (myPicture: PicHandle; dstRect: Rect); 
PROCEDURE KillPicture (myPicture: PicHandle); 


Calculations with Polygons 


FUNCTION OpenPoly : PolyHandle; 

PROCEDURE ClosePoly; 

PROCEDURE KillPoly (poly: PolyHandle) ; 

PROCEDURE OffsetPoly (poly: PolyHandle; dh,dv: INTEGER); 


Graphic Operations on Polygons 


PROCEDURE FramePoly (poly: PolyHandle) ; 
PROCEDURE PaintPoly (poly: PolyHandle) ; 
PROCEDURE ErasePoly (poly: PolyHandle) ; 
PROCEDURE InvertPoly (poly: PolyHandle) ; 
PROCEDURE FillPoly (poly: PolyHandle; pat: Pattern); 


Calculations with Points 


PROCEDURE AddPt 
PROCEDURE SubPt 
PROCEDURE SetPt 
FUNCTION EqualPt 
PROCEDURE LocalToGlobal 
PROCEDURE GlobalToLocal 


srcPt: Point; VAR dstPt: Point); 
srcPt: Point; VAR dstPt: Point); 
VAR pt: Point; h,v: INTEGER); 
ptl,pt2: Point) : BOOLEAN; 

VAR pt: Point); 

VAR pt: Point); 


Re 


Miscellaneous Routines 


FUNCTION Random : eee 

FUNCTION GetPixel (h INTEGER) : BOOLEAN; 

PROCEDURE Stuf fHex (thingptr: Ptr; s: Str255); 

PROCEDURE ScalePt (VAR pt: Point; srcRect,dstRect: Rect); 
PROCEDURE MapPt (VAR pt: Point; srcRect,dstRect: Rect); 
PROCEDURE MapRect (VAR r: Rect; srcRect,dstRect: Rect); 
PROCEDURE MapRgn (rgn: RgnHandle; srcRect,dstRect: Rect); 
PROCEDURE MapPoly (poly: PolyHandle; srcRect,dstRect: Rect); 


Customizing QuickDraw Operations 


PROCEDURE SetStdProcs (VAR procs: QDProcs); 


PROCEDURE StdText (byteCount: INTEGER; textBuf: Ptr; 
numer,denom: Point); 

PROCEDURE StdLine (newPt: Point); 

PROCEDURE StdRect (verb: GrafVerb; r: Rect); 
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PROCEDURE StdRRect (verb: GrafVerb; r: Rect; 
ovalwidth,ovalHeight: INTEGER); 


PROCEDURE StdOval (verb: GrafVerb; r: Rect); 
PROCEDURE StdArc (verb: GrafVerb; r: Rect; 
startAngle,arcAngle: INTEGER); 
PROCEDURE StdPoly (verb: GrafVerb; poly: PolyHandle); 
PROCEDURE StdRgn (verb: GrafVerb; rgn: RgnHandle) ; 
PROCEDURE StdBits (VAR srcBits: BitMap; VAR srcRect,dstRect: Rect; 


mode: INTEGER; maskRgn: RgnHandle) ; 
PROCEDURE StdComment (kind,dataSize: INTEGER; dataHandle: Handle); 
FUNCTION StdTxMeas (byteCount: INTEGER; textAddr: Ptr; 

VAR numer, denom: Point; 

VAR info: FontInfo) : INTEGER; 
PROCEDURE StdGetPic (dataPtr: Ptr; byteCount: INTEGER); 
PROCEDURE StdPutPic (dataPtr: Ptr; byteCount: INTEGER); 


Assembly-Language Information 

Constants 

; Size in bytes of QuickDraw global variables 
grafSize . EQU 206 


; Source transfer modes 


srcCopy .EQU 0 
srcor . EQU 1 
srcxor . EQU 2 
srcBic . EQU 3 
notSrcCopy .EQU 4 
notSrcOr . EQU 5 
notSrcxor . EQU 6 
notSrcBic . EQU 7 


» Pattern transfer modes 


patCopy . EQU 8 
patOr . EQU 9 
patXor .EQU 10 
patBic . EQU 11 
notPatCopy .EQU 12 
notPatOr . EQU 13 


notPatXor . EQU 14 
notPatBic . EQU 15 


» Standard colors for ForeColor and BackColor 


blackColor . EQU 33 
whiteColor . EQU 30 
redColor . EQU 205 
greenColor .EQU 341 
blueColor . EQU 409 
cyanColor .EQU 273 
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magentaColor .EQU 137 
yellowColor . EQU 69 


; Standard picture comments 


picLParen .EQU 0 
picRParen .EQU 1 


; Character style 


boldBit . EQU 0 
italicBit . EQU 1 

ulineBit . EQU 2 
outlineBit . EQU 3 
shadowBit . EQU 4 
condenseBit .EQU 5 
extendBit . EQU 6 

; Graphic operations 

frame . EQU 0 

paint . EQU 1 

erase . EQU 2 

invert .EQU 3 

fill . EQU 4 

Point Data Structure 

V Vertical coordinate (word) 
h Horizontal coordinate (word) 


Rectangle Data Structure 


top Vertical coordinate of top left corner (word) 

left Horizontal coordinate of top left corner (word) 
bottom Vertical coordinate of bottom right corner (word) 
right Horizontal coordinate of bottom right corner (word) 
topLeft Top left corner (point; long) 


botRight Bottom right corner (point; long) 


Region Data Structure 


rgnSize Size in bytes (word) 
rgnBBox Enclosing rectangle (8 bytes) 
rgnData More data if not rectangular 


Bit Map Data Structure 


baseAddr Pointer to bit image 

rowBytes Row width (word) 

bounds Boundary rectangle (8 bytes) 

bitMapRec Size in bytes of bit map data structure 


Cursor Data Structure 


data Cursor image (32 bytes) 
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mask Cursor mask (32 bytes) 
hotSpot Point aligned with mouse (long) 
cursRec Size in bytes of cursor data structure 


Structure of QDProcs Record 


textProc Address of text-drawing routine 

LineProc Address of lLine-drawing routine 

rectProc Address of rectangle-drawing routine 
rRectProc Address of roundRect-drawing routine 
ovalProc Address of oval-drawing routine 

arcProc Address of arc/wedge-drawing routine 
polyProc Address of polygon-drawing routine 

rgnProc Address of region-drawing routine 

bitsProc Address of bit-transfer routine 

commentProc Address of routine for processing picture comments 
txMeasProc Address of routine for measuring text width 
getPicProc Address of picture-retrieval routine 
putPicProc Address of picture-saving routine 
qdProcsRec Size in bytes of QDProcs record 


GrafPort Data Structure 


device Font-specific information (word) 
portBits GrafPort's bit map (bitMapRec bytes) 
portBounds Boundary rectangle of grafPort's bit map (8 bytes) 
portRect GrafPort's rectangle (8 bytes) 
visRgn Handle to visible region 

clipRgn Handle to clipping region 

bkPat Background pattern (8 bytes) 
fillPat Fill pattern (8 bytes) 

pnLoc Pen location (point; long) 
pnSize Pen size (point; long) 

pnMode Pen's transfer mode (word) 

pnPat Pen pattern (8 bytes) 

pnVis Pen visibility (word) 

txFont Font number for text (word) 
txFace Text's character style (word) 
txMode Text's transfer mode (word) 
txSize Font size for text (word) 
spExtra Extra space (long) 

fgColor Foreground color (long) 

bkColor Background color (long) 

colrBit Color bit (word) 

picSave Picture being saved 

rgnSave Region being saved 

polySave Polygon being saved 

grafProcs Pointer to QDProcs record 


Picture Data Structure 


picSize Size in bytes (word) 
picFrame Picture frame (rectangle; 8 bytes) 
picData Picture definition data 


Polygon Data Structure 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
QUICKDRAW ¢« 84 of 86 


polySize Size in bytes (word) 
po lyBBox Enclosing rectangle (8 bytes) 
polyPoints Polygon points 


Pen State Data Structure 


psLoc Pen location (point; long) 

psSize Pen size (point; long) 

psMode Pen's transfer mode (word) 

psPat Pen pattern (8 bytes) 

psRec Size in bytes of pen state data structure 


Font Information Data Structure 


ascent Ascent (word) 
descent Descent (word) 
widMax Maximum character width (word) 
leading Leading (word) 


Special Macro Names 


Pascal name Macro name 
SetPortBits _SetPBits 
InvertRect _InverRect 
InvertRoundRect _InverRoundRect 
DisposeRgn _DisposRgn 
SetRectRgn _SetRecRgn 
OffsetRgn _OfSetRgn 
InvertRgn _InverRgn 
ClosePoly _ClosePgon 
Variables 

RndSeed Random number seed (long) 
Routine 

Trap macro On entry On exit 
_GetMaskTable AO: ptr to mask table in ROM 
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Further Reference: 


Font Manager 

Color QuickDraw 

Technical Note #21, QuickDraw's Internal Picture Definition 
Technical Note #26, Character vs. String Operations in QuickDraw 
Technical Note #41, Drawing Into an Offscreen Bitmap 

Technical Note #55, Drawing Icons 

Technical Note #59, Pictures and Clip Regions 

Technical Note #60, Drawing Characters into a Narrow GrafPort 
Technical Note #72, Optimizing for the LaserWriter — Techniques 
Technical Note #73, Color Printing 

Technical Note #86, MacPaint Document Format 

Technical Note #91, Optimizing for the LaserWriter—Picture Comments 
Technical Note #92, The Appearance of Text 

Technical Note #120, Drawing Into an Off-Screen Pixel Map 
Technical Note #154, Displaying Large PICT Files 

Technical Note #155, Handles and Pointers—Identity Crisis 
Technical Note #163, Adding Color With CopyBits 

Technical Note #171, _PackBits Data Format 

Technical Note #181, Every Picture [Comment] Tells Its Story, Don't It? 
Technical Note #183, Position-Independent PostScript 

Technical Note #193, So Many Bitmaps, So Little Time 

Technical Note #194, WMgrPortability 

Technical Note #198, Font/DA Mover, Styled Fonts, and 'NFNT's 
Technical Note #223, Assembly Language Use of InitGraf with MPW 
Technical Note #244, A Leading Cause of Color Cursor Cursing 
Technical Note #252, Plotting Small Icons 

Technical Note #259, Old Style Colors 

32-Bit QuickDraw Documentation 


END OF DOCUMENT 
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